From 922b0f8fadcfe0cface0e3245ae0b2013c2b6927 Mon Sep 17 00:00:00 2001 From: bmcelvee Date: Tue, 14 Jul 2020 17:18:13 -0400 Subject: [PATCH] OSDOCS-1153 Add ConfigMap Documentation --- _topic_map.yml | 3 + builds/builds-configmaps.adoc | 32 +++++ .../builds-configmap-create-from-console.adoc | 30 ++++ modules/builds-configmap-create.adoc | 17 +++ ...s-configmap-creating-from-directories.adoc | 128 ++++++++++++++++++ .../builds-configmap-creating-from-files.adoc | 105 ++++++++++++++ ...onfigmap-creating-from-literal-values.adoc | 45 ++++++ modules/builds-configmap-overview.adoc | 64 +++++++++ ...igmaps-use-case-consuming-in-env-vars.adoc | 93 +++++++++++++ ...figmaps-use-case-consuming-in-volumes.adoc | 88 ++++++++++++ ...e-case-setting-command-line-arguments.adoc | 57 ++++++++ 11 files changed, 662 insertions(+) create mode 100644 builds/builds-configmaps.adoc create mode 100644 modules/builds-configmap-create-from-console.adoc create mode 100644 modules/builds-configmap-create.adoc create mode 100644 modules/builds-configmap-creating-from-directories.adoc create mode 100644 modules/builds-configmap-creating-from-files.adoc create mode 100644 modules/builds-configmap-creating-from-literal-values.adoc create mode 100644 modules/builds-configmap-overview.adoc create mode 100644 modules/builds-configmaps-use-case-consuming-in-env-vars.adoc create mode 100644 modules/builds-configmaps-use-case-consuming-in-volumes.adoc create mode 100644 modules/builds-configmaps-use-case-setting-command-line-arguments.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 6deb05d3e5..f36568d063 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -892,6 +892,9 @@ Topics: - Name: Setting up additional trusted certificate authorities for builds File: setting-up-trusted-ca Distros: openshift-enterprise,openshift-webscale,openshift-origin +- Name: Creating and using ConfigMaps + File: builds-configmaps + Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated --- Name: Pipelines Dir: pipelines diff --git a/builds/builds-configmaps.adoc b/builds/builds-configmaps.adoc new file mode 100644 index 0000000000..dc327472b4 --- /dev/null +++ b/builds/builds-configmaps.adoc @@ -0,0 +1,32 @@ +[id="builds-configmaps"] += Creating and using ConfigMaps +include::modules/common-attributes.adoc[] +:context: builds-configmaps + +toc::[] + +The following sections define ConfigMaps and how to use them. + +include::modules/builds-configmap-overview.adoc[leveloffset=+1] + +include::modules/builds-configmap-create-from-console.adoc[leveloffset=+1] + +include::modules/builds-configmap-create.adoc[leveloffset=+1] + +include::modules/builds-configmap-creating-from-directories.adoc[leveloffset=+2] + +include::modules/builds-configmap-creating-from-files.adoc[leveloffset=+2] + +include::modules/builds-configmap-creating-from-literal-values.adoc[leveloffset=+2] + +[id="builds-configmaps-consuming-configmap-in-pods"] +== Use Cases: Consuming ConfigMaps in Pods + +The following sections describe some uses cases when consuming `ConfigMap` +objects in pods. + +include::modules/builds-configmaps-use-case-consuming-in-env-vars.adoc[leveloffset=+2] + +include::modules/builds-configmaps-use-case-setting-command-line-arguments.adoc[leveloffset=+2] + +include::modules/builds-configmaps-use-case-consuming-in-volumes.adoc[leveloffset=+2] diff --git a/modules/builds-configmap-create-from-console.adoc b/modules/builds-configmap-create-from-console.adoc new file mode 100644 index 0000000000..a1d3b1bcfe --- /dev/null +++ b/modules/builds-configmap-create-from-console.adoc @@ -0,0 +1,30 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmap-create-from-console_{context}"] += Creating a ConfigMap in the {product-title} web console + +You can create a ConfigMap in the {product-title} web console. + +.Procedure + +* To create a ConfigMap as a cluster administrator: ++ +. In the Administrator perspective, select `Workloads` -> `Config Maps`. ++ +. At the top right side of the page, select *Create Config Map*. ++ +. Enter the contents of your ConfigMap. ++ +. Select *Create*. + +* To create a ConfigMap as a developer: ++ +. In the Developer perspective, select `Config Maps`. ++ +. At the top right side of the page, select *Create Config Map*. ++ +. Enter the contents of your ConfigMap. ++ +. Select *Create*. diff --git a/modules/builds-configmap-create.adoc b/modules/builds-configmap-create.adoc new file mode 100644 index 0000000000..33e9c15fe5 --- /dev/null +++ b/modules/builds-configmap-create.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmap-create_{context}"] += Creating a ConfigMap + +You can use the following command to create a ConfigMap from directories, specific files, or literal values. + +.Procedure + +* Create a ConfigMap: + +[source,terminal] +---- +$ oc create configmap [options] +---- diff --git a/modules/builds-configmap-creating-from-directories.adoc b/modules/builds-configmap-creating-from-directories.adoc new file mode 100644 index 0000000000..64f0f7315e --- /dev/null +++ b/modules/builds-configmap-creating-from-directories.adoc @@ -0,0 +1,128 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmap-creating-from-directories_{context}"] += Creating a ConfigMap from a directory + +You can create a ConfigMap from a directory. This method allows you to use multiple files within a directory to create a ConfigMap. + +.Procedure + +The following example procedure outlines how to create a ConfigMap from a directory. + +. Start with a directory with some files that already contain the data with which you want to populate a ConfigMap: ++ +[source,terminal] +---- +$ ls example-files +---- ++ +.Example output +[source,terminal] +---- +game.properties +ui.properties +---- ++ +[source,terminal] +---- +$ cat example-files/game.properties +---- ++ +.Example output +[source,terminal] +---- +enemies=aliens +lives=3 +enemies.cheat=true +enemies.cheat.level=noGoodRotten +secret.code.passphrase=UUDDLRLRBABAS +secret.code.allowed=true +secret.code.lives=30 +---- ++ +[source,terminal] +---- +$ cat example-files/ui.properties +---- ++ +.Example output +[source,terminal] +---- +color.good=purple +color.bad=yellow +allow.textmode=true +how.nice.to.look=fairlyNice +---- + +. Create a ConfigMap holding the content of each file in this directory by entering the following command: ++ +[source,terminal] +---- +$ oc create configmap game-config \ + --from-file=example-files/ +---- ++ +When the `--from-file` option points to a directory, each file directly in that directory is used to populate a key in the ConfigMap, where the name of the key is the file name, and the value of the key is the content of the file. ++ +For example, the previous command creates the following ConfigMap: ++ +[source,terminal] +---- +$ oc describe configmaps game-config +---- ++ +.Example output +[source,terminal] +---- +Name: game-config +Namespace: default +Labels: +Annotations: + +Data + +game.properties: 158 bytes +ui.properties: 83 bytes +---- ++ +You can see that the two keys in the map are created from the file names in the +directory specified in the command. Because the content of those keys might be +large, the output of `oc describe` only shows the names of the keys and their +sizes. ++ +. Enter the `oc get` command for the object with the `-o` option to see the values of the keys: ++ +[source,terminal] +---- +$ oc get configmaps game-config -o yaml +---- ++ +.Example output +[source,yaml] +---- +apiVersion: v1 +data: + game.properties: |- + enemies=aliens + lives=3 + enemies.cheat=true + enemies.cheat.level=noGoodRotten + secret.code.passphrase=UUDDLRLRBABAS + secret.code.allowed=true + secret.code.lives=30 + ui.properties: | + color.good=purple + color.bad=yellow + allow.textmode=true + how.nice.to.look=fairlyNice +kind: ConfigMap +metadata: + creationTimestamp: 2016-02-18T18:34:05Z + name: game-config + namespace: default + resourceVersion: "407"- + selflink: /api/v1/namespaces/default/configmaps/game-config + uid: 30944725-d66e-11e5-8cd0-68f728db1985 +---- diff --git a/modules/builds-configmap-creating-from-files.adoc b/modules/builds-configmap-creating-from-files.adoc new file mode 100644 index 0000000000..b485a186f4 --- /dev/null +++ b/modules/builds-configmap-creating-from-files.adoc @@ -0,0 +1,105 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmap-creating-from-files_{context}"] += Creating a ConfigMap from a file + +You can create a ConfigMap from a file. + +.Procedure + +The following example procedure outlines how to create a ConfigMap from a file. + +[NOTE] +==== +If you create a configmap from a file, you can include files containing non-UTF8 data that are placed in this field without corrupting the non-UTF8 data. +{product-title} detects binary files and transparently encodes the file as `MIME`. On the server, the `MIME` payload is decoded and stored without corrupting the data. +==== + +You can pass the `--from-file` option multiple times to the CLI. The following example yields equivalent results to the creating from directories example. + +. Create the ConfigMap specifying a specific file: ++ +[source,terminal] +---- +$ oc create configmap game-config-2 \ + --from-file=example-files/game.properties \ + --from-file=example-files/ui.properties +---- ++ +. Verify the results: ++ +[source,terminal] +---- +$ oc get configmaps game-config-2 -o yaml +---- ++ +.Example output +[source,yaml] +---- +apiVersion: v1 +data: + game.properties: |- + enemies=aliens + lives=3 + enemies.cheat=true + enemies.cheat.level=noGoodRotten + secret.code.passphrase=UUDDLRLRBABAS + secret.code.allowed=true + secret.code.lives=30 + ui.properties: | + color.good=purple + color.bad=yellow + allow.textmode=true + how.nice.to.look=fairlyNice +kind: ConfigMap +metadata: + creationTimestamp: 2016-02-18T18:52:05Z + name: game-config-2 + namespace: default + resourceVersion: "516" + selflink: /api/v1/namespaces/default/configmaps/game-config-2 + uid: b4952dc3-d670-11e5-8cd0-68f728db1985 +---- + +You can specify the key to set in a ConfigMap for content imported from a file. This can be set by passing a `key=value` expression to the `--from-file` option. For example: + +. Create the ConfigMap specifying a key-value pair: ++ +[source,terminal] +---- +$ oc create configmap game-config-3 \ + --from-file=game-special-key=example-files/game.properties +---- + +. Verify the results: ++ +[source,terminal] +---- +$ oc get configmaps game-config-3 -o yaml +---- ++ +.Example output +[source,yaml] +---- +apiVersion: v1 +data: + game-special-key: |- <1> + enemies=aliens + lives=3 + enemies.cheat=true + enemies.cheat.level=noGoodRotten + secret.code.passphrase=UUDDLRLRBABAS + secret.code.allowed=true + secret.code.lives=30 +kind: ConfigMap +metadata: + creationTimestamp: 2016-02-18T18:54:22Z + name: game-config-3 + namespace: default + resourceVersion: "530" + selflink: /api/v1/namespaces/default/configmaps/game-config-3 + uid: 05f8da22-d671-11e5-8cd0-68f728db1985 +---- +<1> This is the key that you set in the preceding step. diff --git a/modules/builds-configmap-creating-from-literal-values.adoc b/modules/builds-configmap-creating-from-literal-values.adoc new file mode 100644 index 0000000000..0a86bf5541 --- /dev/null +++ b/modules/builds-configmap-creating-from-literal-values.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmap-creating-from-literal-values_{context}"] += Creating a ConfigMap from literal values + +You can supply literal values for a ConfigMap. + +.Procedure + +The `--from-literal` option takes a `key=value` syntax that allows literal values to be supplied directly on the command line. + +. Create a ConfigMap specifying a literal value: ++ +[source,terminal] +---- +$ oc create configmap special-config \ + --from-literal=special.how=very \ + --from-literal=special.type=charm +---- + +. Verify the results: ++ +[source,terminal] +---- +$ oc get configmaps special-config -o yaml +---- ++ +.Example output +[source,yaml] +---- +apiVersion: v1 +data: + special.how: very + special.type: charm +kind: ConfigMap +metadata: + creationTimestamp: 2016-02-18T19:14:38Z + name: special-config + namespace: default + resourceVersion: "651" + selflink: /api/v1/namespaces/default/configmaps/special-config + uid: dadce046-d673-11e5-8cd0-68f728db1985 +---- diff --git a/modules/builds-configmap-overview.adoc b/modules/builds-configmap-overview.adoc new file mode 100644 index 0000000000..4f2199a0ae --- /dev/null +++ b/modules/builds-configmap-overview.adoc @@ -0,0 +1,64 @@ +// Module included in the following assemblies: +// +// * builds/builds-configmaps.adoc + +[id="builds-configmap-overview_{context}"] += Understanding ConfigMaps + +Many applications require configuration using some combination of configuration files, command line arguments, and environment variables. In {product-title}, these configuration artifacts are decoupled from image content in order to keep containerized applications portable. + +The ConfigMap object provides mechanisms to inject containers with configuration data while keeping containers agnostic of {product-title}. A ConfigMap can be used to store fine-grained information like individual properties or coarse-grained information like entire configuration files or JSON blobs. + +The ConfigMap API object holds key-value pairs of configuration data that can be consumed in Pods or used to store configuration data for system components such as controllers. For example: + +.ConfigMap Object Definition +[source,yaml] +---- +kind: ConfigMap +apiVersion: v1 +metadata: + creationTimestamp: 2016-02-18T19:14:38Z + name: example-config + namespace: default +data: <1> + example.property.1: hello + example.property.2: world + example.property.file: |- + property.1=value-1 + property.2=value-2 + property.3=value-3 +binaryData: + bar: L3Jvb3QvMTAw <2> +---- +<1> Contains the configuration data. +<2> Points to a file that contains non-UTF8 data, for example, a binary Java keystore file. Enter the file data in Base 64. + +[NOTE] +==== +You can use the `binaryData` field when you create a ConfigMap from a binary file, such as an image. +==== + +Configuration data can be consumed in Pods in a variety of ways. A ConfigMap can be used to: + +* Populate environment variable values in containers +* Set command-line arguments in a container +* Populate configuration files in a volume + +Users and system components can store configuration data in a ConfigMap. + +A ConfigMap is similar to a secret, but designed to more conveniently support working with strings that do not contain sensitive information. + +[discrete] +== ConfigMap restrictions + +*A ConfigMap must be created before its contents can be consumed in Pods.* + +Controllers can be written to tolerate missing configuration data. Consult individual components configured by using ConfigMaps on a case-by-case basis. + +*ConfigMap objects reside in a project.* + +They can only be referenced by Pods in the same project. + +*The Kubelet only supports the use of a ConfigMap for Pods it gets from the API server.* + +This includes any Pods created by using the CLI, or indirectly from a replication controller. It does not include Pods created by using the {product-title} node's `--manifest-url` flag, its `--config` flag, or its REST API because these are not common ways to create Pods. diff --git a/modules/builds-configmaps-use-case-consuming-in-env-vars.adoc b/modules/builds-configmaps-use-case-consuming-in-env-vars.adoc new file mode 100644 index 0000000000..69709b7476 --- /dev/null +++ b/modules/builds-configmaps-use-case-consuming-in-env-vars.adoc @@ -0,0 +1,93 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmaps-use-case-consuming-in-env-vars_{context}"] += Populating environment variables in containers by using ConfigMaps + +ConfigMaps can be used to populate individual environment variables in containers or to populate environment variables in containers from all keys that form valid environment variable names. + +As an example, consider the following ConfigMaps: + +.ConfigMap with two environment variables +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: special-config <1> + namespace: default <2> +data: + special.how: very <3> + special.type: charm <3> +---- +<1> Name of the ConfigMap. +<2> The project in which the ConfigMap resides. ConfigMaps can only be referenced by Pods in the same project. +<3> Environment variables to inject. + +.ConfigMap with one environment variable +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: env-config <1> + namespace: default +data: + log_level: INFO <2> +---- +<1> Name of the `ConfigMap`. +<2> Environment variable to inject. + +.Procedure + +* You can consume the keys of this ConfigMap in a Pod using `configMapKeyRef` sections. ++ +.Sample Pod specification configured to inject specific environment variables +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "-c", "env" ] + env: <1> + - name: SPECIAL_LEVEL_KEY <2> + valueFrom: + configMapKeyRef: + name: special-config <3> + key: special.how <4> + - name: SPECIAL_TYPE_KEY + valueFrom: + configMapKeyRef: + name: special-config <3> + key: special.type <4> + optional: true <5> + envFrom: <6> + - configMapRef: + name: env-config <7> + restartPolicy: Never +---- +<1> Stanza to pull the specified environment variables from a ConfigMap. +<2> Name of a Pod environment variable that you are injecting a key's value into. +<3> Name of the ConfigMap to pull specific environment variables from. +<4> Environment variable to pull from the ConfigMap. +<5> Makes the environment variable optional. As optional, the Pod will be started even if the specified ConfigMap and keys do not exist. +<6> Stanza to pull all environment variables from a ConfigMap. +<7> Name of the ConfigMap to pull all environment variables from. ++ +When this Pod is run, the Pod logs will include the following output: ++ +---- +SPECIAL_LEVEL_KEY=very +log_level=INFO +---- + +[NOTE] +==== +`SPECIAL_TYPE_KEY=charm` is not listed in the example output because `optional: true` is set. +==== diff --git a/modules/builds-configmaps-use-case-consuming-in-volumes.adoc b/modules/builds-configmaps-use-case-consuming-in-volumes.adoc new file mode 100644 index 0000000000..9c5e65eac2 --- /dev/null +++ b/modules/builds-configmaps-use-case-consuming-in-volumes.adoc @@ -0,0 +1,88 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmaps-use-case-consuming-in-volumes_{context}"] += Injecting content into a volume by using ConfigMaps + +You can inject content into a volume by using ConfigMaps. + +.Example ConfigMap +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: special-config + namespace: default +data: + special.how: very + special.type: charm +---- + +.Procedure + +You have a couple different options for injecting content into a volume by using ConfigMaps. + +* The most basic way to inject content into a volume by using a ConfigMap is to populate the volume with files where the key is the file name and the content of the file is the value of the key: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "cat", "/etc/config/special.how" ] + volumeMounts: + - name: config-volume + mountPath: /etc/config + volumes: + - name: config-volume + configMap: + name: special-config <1> + restartPolicy: Never +---- +<1> File containing key. ++ +When this pod is run, the output of the cat command will be: ++ +---- +very +---- + +* You can also control the paths within the volume where ConfigMap keys are projected: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "cat", "/etc/config/path/to/special-key" ] + volumeMounts: + - name: config-volume + mountPath: /etc/config + volumes: + - name: config-volume + configMap: + name: special-config + items: + - key: special.how + path: path/to/special-key <1> + restartPolicy: Never +---- +<1> Path to ConfigMap key. ++ +When this pod is run, the output of the cat command will be: ++ +---- +very +---- diff --git a/modules/builds-configmaps-use-case-setting-command-line-arguments.adoc b/modules/builds-configmaps-use-case-setting-command-line-arguments.adoc new file mode 100644 index 0000000000..fa2ac31249 --- /dev/null +++ b/modules/builds-configmaps-use-case-setting-command-line-arguments.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +//* builds/builds-configmaps.adoc + +[id="builds-configmaps-use-case-setting-command-line-arguments_{context}"] += Setting command-line arguments for container commands with ConfigMaps + +A ConfigMap can also be used to set the value of the commands or arguments in a container. This is accomplished by using the Kubernetes substitution syntax `$(VAR_NAME)`. Consider the following ConfigMaps: + +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: special-config + namespace: default +data: + special.how: very + special.type: charm +---- + +.Procedure + +* To inject values into a command in a container, you must consume the keys you want to use as environment variables, as in the consuming ConfigMaps in environment variables use case. Then you can refer to them in a container's command using the `$(VAR_NAME)` syntax. ++ +.Sample Pod specification configured to inject specific environment variables +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ] <1> + env: + - name: SPECIAL_LEVEL_KEY + valueFrom: + configMapKeyRef: + name: special-config + key: special.how + - name: SPECIAL_TYPE_KEY + valueFrom: + configMapKeyRef: + name: special-config + key: special.type + restartPolicy: Never +---- +<1> Inject the values into a command in a container using the keys you want to use as environment variables. ++ +When this Pod is run, the output from the echo command run in the test-container container is as follows: ++ +---- +very charm +----