kubernetes
/
kubectl
mirror of https://github.com/kubernetes/kubectl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
kubectl/cmd/kustomize/demos/helloWorld.md

8.8 KiB
Raw Blame History

Demo: hello world with instances

Steps:

  1. Clone an existing configuration as a base.
  2. Customize it.
  3. Create two different overlays (staging and production) from the customized base.
  4. Run kustomize and kubectl to deploy staging and production.

First define a place to work:

DEMO_HOME=$(mktemp -d)

Alternatively, use

DEMO_HOME=~/hello

Clone an example

Let's run the hello service. Here's an existing config for it.

Clone this config to a directory called base:

git clone \
    https://github.com/kinflate/example-hello \
    $DEMO_HOME/base

tree $DEMO_HOME

Expecting something like:

/tmp/tmp.IyYQQlHaJP
└── base
    ├── configMap.yaml
    ├── deployment.yaml
    ├── kustomize.yaml
    ├── LICENSE
    ├── README.md
    └── service.yaml

One could immediately apply these resources to a cluster:

kubectl apply -f $DEMO_HOME/base

to instantiate the hello service. kubectl would only recognize the resource files.

The Base Manifest

The base directory has a manifest file:

BASE=$DEMO_HOME/base
more $BASE/kustomize.yaml

Run kustomize on the base to emit customized resources to stdout:

kustomize build $BASE

Customize the base

A first customization step could be to change the app label applied to all resources:

sed -i 's/app: hello/app: my-hello/' \
    $BASE/kustomize.yaml

See the effect:

kustomize build $BASE | grep -C 3 app:

Create Overlays

Create a staging and production overlay:

  • Staging enables a risky feature not enabled in production.
  • Production has a higher replica count.
  • Web server greetings from these cluster instances will differ from each other.
OVERLAYS=$DEMO_HOME/overlays
mkdir -p $OVERLAYS/staging
mkdir -p $OVERLAYS/production

Staging Manifest

In the staging directory, make a manifest defining a new name prefix, and some different labels.

cat <<'EOF' >$OVERLAYS/staging/kustomize.yaml
kustomizationName: makes-staging-hello
namePrefix: staging-
objectLabels:
  instance: staging
  org: acmeCorporation
objectAnnotations:
  note: Hello, I am staging!
bases:
- ../../base
patches:
- map.yaml
EOF

Staging Patch

Add a configMap customization to change the server greeting from Good Morning! to Have a pineapple!

Also, enable the risky flag.

cat <<EOF >$OVERLAYS/staging/map.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: the-map
data:
  altGreeting: "Have a pineapple!"
  enableRisky: "true"
EOF

Production Manifest

In the production directory, make a manifest with a different name prefix and labels.

cat <<EOF >$OVERLAYS/production/kustomize.yaml
kustomizationName: makes-production-tuthello
namePrefix: production-
objectLabels:
  instance: production
  org: acmeCorporation
objectAnnotations:
  note: Hello, I am production!
bases:
- ../../base
patches:
- deployment.yaml
EOF

Production Patch

Make a production patch that increases the replica count (because production takes more traffic).

cat <<EOF >$OVERLAYS/production/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: the-deployment
spec:
  replicas: 10
EOF

Compare overlays

DEMO_HOME now contains:

  • a base directory - a slightly customized clone of the original configuration, and

  • an overlays directory, containing the manifests and patches required to create distinct staging and production instances in a cluster.

Review the directory structure and differences:

tree $DEMO_HOME

Expecting something like:

/tmp/tmp.IyYQQlHaJP1
├── base
│   ├── configMap.yaml
│   ├── deployment.yaml
│   ├── kustomize.yaml
│   ├── LICENSE
│   ├── README.md
│   └── service.yaml
└── overlays
    ├── production
    │   ├── deployment.yaml
    │   └── kustomize.yaml
    └── staging
        ├── kustomize.yaml
        └── map.yaml

Compare the output directly to see how staging and production differ:

diff \
  <(kustomize build $OVERLAYS/staging) \
  <(kustomize build $OVERLAYS/production) |\
  more

The first part of the difference output should look something like

<   altGreeting: Have a pineapple!
<   enableRisky: "true"
---
>   altGreeting: Good Morning!
>   enableRisky: "false"
8c8
<     note: Hello, I am staging!
---
>     note: Hello, I am production!
11c11
<     instance: staging
---
>     instance: production
13c13
(...truncated)

Deploy

The individual resource sets are:

kustomize build $OVERLAYS/staging

kustomize build $OVERLAYS/production

To deploy, pipe the above commands to kubectl apply:

kustomize build $OVERLAYS/staging |\
    kubectl apply -f -

kustomize build $OVERLAYS/production |\
   kubectl apply -f -

Rolling updates

Review

The hello-world deployment running in this cluster is configured with data from a configMap.

The deployment refers to this map by name:

grep -C 2 configMapKeyRef $DEMO_HOME/base/deployment.yaml

Changing the data held by a live configMap in a cluster is considered bad practice. Deployments have no means to know that the configMaps they refer to have changed, so such updates have no effect.

The recommended way to change a deployment's configuration is to

  1. create a new configMap with a new name,
  2. patch the deployment, modifying the name value of the appropriate configMapKeyRef field.

This latter change initiates rolling update to the pods in the deployment. The older configMap, when no longer referenced by any other resource, is eventually garbage collected.

How this works with kustomize

The staging instance here has a configMap patch:

cat $OVERLAYS/staging/map.yaml

This patch is by definition a named but not necessarily complete resource spec intended to modify a complete resource spec.

The resource it modifies is here:

cat $DEMO_HOME/base/configMap.yaml

For a patch to work, the names in the metadata/name fields must match.

However, the name values specified in the file are not what gets used in the cluster. By design, kustomize modifies these names. To see the names ultimately used in the cluster, just run kustomize:

kustomize build $OVERLAYS/staging |\
    grep -B 8 -A 1 staging-the-map

The configMap name is prefixed by staging-, per the namePrefix field in $OVERLAYS/staging/kustomize.yaml.

The suffix to the configMap name is generated from a hash of the maps content - in this case the name suffix is hhhhkfmgmk:

kustomize build $OVERLAYS/staging | grep hhhhkfmgmk

Now modify the map patch, to change the greeting the server will use:

sed -i 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml

Run kustomize again to see the new names:

kustomize build $OVERLAYS/staging |\
    grep -B 8 -A 1 staging-the-map

Confirm that the change in configMap content resulted in three new names ending in khk45ktkd9 - one in the configMap name itself, and two in the deployment that uses the map:

test 3 == $(kustomize build $OVERLAYS/staging | grep khk45ktkd9 | wc -l)

Applying these resources to the cluster will result in a rolling update of the deployments pods, retargetting them from the hhhhkfmgmk maps to the khk45ktkd9 maps. The system will later garbage collect the unused maps.

Rollback

To rollback, one would undo whatever edits were made to the configuation in source control, then rerun kustomize on the reverted configuration and apply it to the cluster.