kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-05-17 18:25:26 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Getting started guide part 2 (#4748)

Browse Source 
* rename overlays

* add further examples in first kustomization

* fix typo

* fix formatting

* fix typo

* fix formatting

* fix typos

* restore overlay names to production and staging in original content

* restore overlay names to production and staging in original content

* restore overlay names to production and staging in new content

* updated doc to use "you/your" vs "we/our", and updated to use US spelling

* fix capitalization

* Update site/content/en/docs/Getting started/first_kustomization.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* Update site/content/en/docs/Getting started/first_kustomization.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* add "patch:" for patches in kustomization, and add url link

* Update site/content/en/docs/Getting started/first_kustomization.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* fix typo

Co-authored-by: Katrina Verey <kn.verey@gmail.com>
This commit is contained in:
Robert Facciol
2022-08-16 20:11:08 +02:00
committed by GitHub
parent 2ec4b971e9
commit 26fcafdb57
1 changed files with 413 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

432
site/content/en/docs/Getting started/first_kustomization.md
View File

@@ -6,12 +6,13 @@ weight: 20
description: >
A step by step tutorial for absolute kustomize beginners
---
[kustomization reference]: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/
This page will help you get started with this amazing tool called kustomize! We will start off with a simple nginx deployment manifest and then use it to explore kustomize basics.
This page will help you get started with this amazing tool called kustomize! You will start off with a simple nginx deployment manifest and then use it to explore kustomize basics.
### Create your resource manifests and Kustomization
### Create resource manifests and Kustomization
Let's start off by creating our nginx deployment and service manifests in a dedicated folder:
Let's start off by creating your nginx deployment and service manifests in a dedicated folder:
```bash
mkdir kustomize-example
@@ -58,7 +59,7 @@ spec:
EOF
```
Now that we have our `deployment.yaml` and `service.yaml` files created, let's create our Kustomization. We can think of Kustomization as the set of instructions that tell kustomize what it needs to do, and it is defined in a file named `kustomization.yaml`:
Now that you have your `deployment.yaml` and `service.yaml` files created, let's create your Kustomization. You can think of Kustomization as the set of instructions that tell kustomize what it needs to do, and it is defined in a file named `kustomization.yaml`:
```bash
cat <<'EOF' >kustomization.yaml
@@ -71,7 +72,7 @@ resources:
EOF
```
In this kustomization file, we are telling kustomize to include the `deployment.yaml` and `service.yaml` as its resources. If we now run `kustomize build .` from our current working directory, kustomize will generate a manifest containing the contents of our `deployment.yaml` and `service.yaml` files with no additional changes.
In this kustomization file, you are telling kustomize to include the `deployment.yaml` and `service.yaml` as its resources. If you now run `kustomize build .` from your current working directory, kustomize will generate a manifest containing the contents of your `deployment.yaml` and `service.yaml` files with no additional changes.
```yaml
$ kustomize build .
@@ -113,9 +114,9 @@ spec:
- containerPort: 80
```
### Customise your resources
### Customize resources
So far we have not used kustomize to do any modifications, so let's see how we can do that. Kustomize comes with a considerable number of transformers that apply changes to our manifests, and in this section we will have a look at the `namePrefix` transformer. This transformer will add a prefix to the deployment and service names. Modify the `kustomization.yaml` file as follows:
So far kustomize has not been used to do any modifications, so let's see how you can do that. Kustomize comes with a considerable number of transformers that apply changes to your manifests, and in this section you will have a look at the `namePrefix` transformer. This transformer will add a prefix to the deployment and service names. Modify the `kustomization.yaml` file as follows:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
@@ -128,7 +129,7 @@ resources:
- service.yaml
```
After re-building we see can see our modified manifest which now has the prefixed deployment and service names:
After re-building you see can see your modified manifest which now has the prefixed deployment and service names:
```yaml
$ kustomize build .
@@ -172,9 +173,9 @@ spec:
### Create variants using overlays
Now let's assume we need to deploy the nginx manifests from the previous section to two environments called `Staging` and `Production`. The manifests for these two environments will be mostly identical, with only a few minor changes between them. We call these two mostly identical manifests "variants". Traditionally to create variants, we could duplicate the manifests and apply the changes manually or rely on some templating engine. With kustomize, we can avoid templating and duplication of our manifests and apply the different changes we need using overlays. With this approach, the `base` would contain the common part of the our variants and the `overlays` contain our environment specific changes.
Now let's assume that you need to deploy the nginx manifests from the previous section to two environments called `Staging` and `Production`. The manifests for these two environments will be mostly identical, with only a few minor changes between them. These two mostly identical manifests are called "variants". Traditionally, to create variants you could duplicate the manifests and apply the changes manually or rely on some templating engine. With kustomize you can avoid templating and duplication of your manifests and apply the different changes you need using overlays. With this approach, the `base` contains what your environments have in common, and the `overlays` contain your environment-specific changes.
Create the `kustomization.yaml` files for our two overlays and move the files we have so far into `base`:
Create the `kustomization.yaml` files for your two overlays and move the files you have so far into `base`:
```bash
mkdir -p base overlays/staging overlays/production
@@ -198,7 +199,7 @@ resources:
EOF
```
The kustomization files for the overlays include just the `base` folder, so if you were to run `kustomize build` on the overlay folders at this point you would get the same output you would get if you built `base`. It is important to note that bases can be included in the `resources` field in the same way that we included our other deployment and service resource files.
The kustomization files for the overlays include just the `base` folder, so if you were to run `kustomize build` on the overlay folders at this point you would get the same output you would get if you built `base`. It is important to note that bases can be included in the `resources` field in the same way that your other deployment and service resource files were included.
The directory structure you created so far should look like this:
@@ -215,9 +216,9 @@ kustomize-example
└── kustomization.yaml
```
### Customising our overlays
### Customizing overlays
For the purposes our example, let's define some requirements of how our deployment should look like in the two environments:
For the purposes of this example, let's define some requirements for how your deployment should look like in the two environments:
|Requirement| Production | Staging |
|-----------|------------------------------------|-----------------------------|
@@ -226,7 +227,7 @@ For the purposes our example, let's define some requirements of how our deployme
|Replicas |3 |2 |
We can achieve the names required by making use of `namePrefix` and `nameSuffix` as follows:
You can achieve the names required by making use of `namePrefix` and `nameSuffix` as follows:
_kustomize-example/overlays/production/kustomization.yaml_:
@@ -253,7 +254,7 @@ resources:
- ../../base
```
The build output for our Production overlay would now be:
The build output for your `Production` overlay would now be:
```yaml
$ kustomize build overlays/production/
@@ -295,10 +296,10 @@ spec:
- containerPort: 80
```
It is important to note here that the name for _both_ the `deployment` and the `service` were updated with the `namePrefix` and `nameSuffix` defined. If we had additional kubernetes objects (like an `ingress`) their name would be updated as well.
It is important to note here that the name for _both_ the `deployment` and the `service` were updated with the `namePrefix` and `nameSuffix` defined. If you had additional Kubernetes objects (like an `ingress`) their name would be updated as well.
Moving on to our next requirements, we can set the namespace and the number of replicas we want by using `namespace` and `replicas` respectively:
Moving on to the next requirements, you can set the namespace and the number of replicas you want by using `namespace` and `replicas` respectively:
_kustomize-example/overlays/production/kustomization.yaml_:
@@ -337,7 +338,7 @@ resources:
- ../../base
```
Note that the deployment name being referenced in `replicas` is the modified name that was output by `base`. Looking at the output of `kustomize build` we can see that we have met all the requirements we set out to meet:
Note that the deployment name being referenced in `replicas` is the modified name that was output by `base`. Looking at the output of `kustomize build` you can see that all the requirements that were set have been met:
_Production overlay build_:
@@ -411,7 +412,7 @@ metadata:
name: env2-example-nginx-staging
namespace: staging ### namespace has been set to staging
spec:
replicas: 2 ### replicas have been from 1 to 2
replicas: 2 ### replicas have been updated from 1 to 2
selector:
matchLabels:
app: nginx
@@ -426,3 +427,396 @@ spec:
ports:
- containerPort: 80
```
### Further customizations
Now that you have seen how kustomize works, let's add a few more requirements:
|Requirement| Production | Staging |
|-----------|------------------------------------|-----------------------------|
|Image |nginx:1.20.2 |nginx:latest |
|Label |variant=var1 |variant=var2 |
|Env Var |ENVIRONMENT=prod |ENVIRONMENT=stg |
To keep the example brief, only the changes for the `Production` overlay will be shown and then the updated overlay files and builds for both overlays will be presented at the end. The specific image tag can be set by making use of the `images` field. Add the following to the kustomization files in your overlays:
```yaml
images:
- name: nginx
newTag: 1.20.2 ## For the Staging overlay set this to 'latest'
```
For setting the label, you can use the `labels` field. Add the following to the kustomization files in your overlays:
```yaml
labels:
- pairs:
variant: var1 ## For the Staging overlay set this to 'var2'
includeSelectors: false # Setting this to false so that the label is not added to the selectors
includeTemplates: true # Setting this to true will make the label available also on the pod and not just the deployment
```
At this point, your kustomization files for your `Production` overlay should be as follows:
_kustomize-example/overlays/production/kustomization.yaml_:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: env1-
nameSuffix: -production
namespace: production
replicas:
- name: example-nginx
count: 3
images:
- name: nginx
newTag: 1.20.2
labels:
- pairs:
variant: var1
includeSelectors: false
includeTemplates: true
resources:
- ../../base
```
Rebuilding the `Production` overlay gives the following:
```yaml
$ kustomize build overlays/production/
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
variant: var1 ### label has been set here
name: env1-example-nginx-production
namespace: production
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nginx
variant: var1 ### label has been set here
name: env1-example-nginx-production
namespace: production
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
variant: var1 ### label has been set here
spec:
containers:
- image: nginx:1.20.2 ### image tag has been set to 1.20.2
name: nginx
ports:
- containerPort: 80
```
The last requirement to meet is to set the environment variable, and to do that you will create a patch. To do this, create the following file for the `Production` overlay:
```bash
cat <<'EOF' >overlays/production/patch-env-vars.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-nginx
spec:
template:
spec:
containers:
- name: nginx
env:
- name: ENVIRONMENT
value: prod
EOF
```
Next step, add a reference to that patch file in `kustomization.yaml`:
```yaml
patches:
- path: patch-env-vars.yaml
```
One important thing to note here is that the name of the deployment used is the name that you are getting from the base and not the deployment name that has the prefix and suffix added.
Rebuilding the overlay shows that the environment variable has been added to your container:
```yaml
$ kustomize build overlays/production/
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
variant: var1
name: env1-example-nginx-production
namespace: production
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nginx
variant: var1
name: env1-example-nginx-production
namespace: production
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
variant: var1
spec:
containers:
- env:
- name: ENVIRONMENT ### Environment variable has been added here
value: prod
image: nginx:1.20.2
name: nginx
ports:
- containerPort: 80
```
Looking at the output of `kustomize build` you can see that the additional requirements that were set have now been met. Below are the files as they should be at this point in your overlays and the `kustomize build` output:
_kustomize-example/overlays/production/kustomization.yaml_:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: env1-
nameSuffix: -production
namespace: production
replicas:
- name: example-nginx
count: 3
images:
- name: nginx
newTag: 1.20.2
labels:
- pairs:
variant: var1
includeSelectors: false
includeTemplates: true
resources:
- ../../base
patches:
- path: patch-env-vars.yaml
```
_kustomize-example/overlays/production/patch-env-vars.yaml_:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-nginx
spec:
template:
spec:
containers:
- name: nginx
env:
- name: ENVIRONMENT
value: prod
```
_kustomize-example/overlays/staging/kustomization.yaml_:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: env2-
nameSuffix: -staging
namespace: staging
replicas:
- name: example-nginx
count: 2
images:
- name: nginx
newTag: latest
labels:
- pairs:
variant: var2
includeSelectors: false
includeTemplates: true
resources:
- ../../base
patches:
- path: patch-env-vars.yaml
```
_kustomize-example/overlays/staging/patch-env-vars.yaml_:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-nginx
spec:
template:
spec:
containers:
- name: nginx
env:
- name: ENVIRONMENT
value: stg
```
_Production overlay build_:
```yaml
$ kustomize build overlays/production/
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
variant: var1
name: env1-example-nginx-production
namespace: production
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nginx
variant: var1
name: env1-example-nginx-production
namespace: production
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
variant: var1
spec:
containers:
- env:
- name: ENVIRONMENT
value: prod
image: nginx:1.20.2
name: nginx
ports:
- containerPort: 80
```
_Staging overlay build_:
```yaml
$ kustomize build overlays/staging/
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx
variant: var2
name: env2-example-nginx-staging
namespace: staging
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nginx
variant: var2
name: env2-example-nginx-staging
namespace: staging
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
variant: var2
spec:
containers:
- env:
- name: ENVIRONMENT
value: stg
image: nginx:latest
name: nginx
ports:
- containerPort: 80
```
### Next steps
Congratulations on making it to the end of this tutorial. As a summary for you, these are the customizations that were presented in this tutorial:
- Add a name prefix and a name suffix
- Set the namespace for your resources
- Set the number of replicas for your deployment
- Set the image to use
- Add a label to your resources
- Add an environment variable to a container by using a patch
These are just a few of the things kustomize can do. If you are interested to learn more, the [kustomization reference] is your next step. You will see how you can use components to define base resources and add them to specific overlays where needed, use generators to create configMaps from files, and much more!