ConfigMap

What is ConfigMap

In Kubernetes, ConfigMap is an API object used to store non-confidential data in key-value pairs.

ConfigMap allows users to decouple configuration artifacts from image content to keep containerized applications portable. Pods can consume ConfigMaps as environment variables, command line arguments, or as configuration files in a volume.

In CIS, Configuration artifacts of ConfigMap are agent-specific, meaning that configuration in ConfigMap differs from agent to agent. CIS v2.0 operates in two different agent modes: AS3 or CCCL.

Note

This section covers ConfigMap for agent AS3 only, for agent CCCL, please refer to f5-resource.

CIS supports two types of AS3 ConfigMaps, more details explained in subsequent sections:

  • User-defined AS3 ConfigMap
  • Override AS3 Configmap

What is AS3

F5 Application Services (AS3) Extensions use a declarative API, meaning AS3 Extension declarations describe the desired configuration state of a BIG-IP system.

When using AS3 Extensions, CIS sends declaration files using a single Rest API call.

The diagram below depicts the basic data model of the AS3 artifact.

../_images/config-map-diagram.png

What is AS3 ConfigMap

The AS3 ConfigMap hosts AS3 extensions, in JSON format, as a configuration artifact. CIS can manage and orchestrate BIG-IP declaratively through this ConfigMap.

In agent AS3 mode, CIS handles Ingress or Route resources by converting them into AS3 declarations before posting to BIG-IP. When AS3 ConfigMap is configured along with Ingress or Routes, CIS manages ConfigMap and Ingress (or) Routes AS3 declarations separately. While sending an AS3 declaration to BIG-IP, CIS will combine both of these AS3 declarations as a single declaration and POST it to BIG-IP.

Important

Ingress or Routes will always use the single partition (CIS managed partition) in CIS. But AS3 ConfigMap can have more than one partition, except CIS-managed partition. CIS will not process AS3 ConfigMap if configured in CIS-managed partition.

Example AS3 ConfigMap
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
kind: ConfigMap
apiVersion: v1
metadata:
  name: name-of-your-configmap
  namespace: default
  labels:
    f5type: virtual-server
    as3: "true"
data:
  template: |
    {
      "class": "AS3",
      "declaration": {
            "class": "ADC",
            "schemaVersion": "3.18.0",
            "id": "urn:uuid:33045210-3ab8-4636-9b2a-c98d22ab915d",
            "label": "http",
            "remark": "A1 Template",
            "k8s": {
               "class": "Tenant",
               "A1": {
                  "class": "Application",
                  "template": "generic",
                  "a1_80_vs": {
                        "class": "Service_HTTP",
                        "remark": "a1",
                        "virtualAddresses": [
                           "10.192.75.101"
                        ],
                        "pool": "web_pool"
                  },
                  "web_pool": {
                        "class": "Pool",
                        "monitors": [
                           "http"
                        ],
                        "members": [
                           {
                              "servicePort": 8080,
                              "serverAddresses": []
                           }
                        ]
                  }
               }
            }
      }
   }

The image below depicts the example AS3 ConfigMap and its mapping with AS3 objects.

../_images/config-map-diagram2.png

Processing AS3 ConfigMap in CIS

As mentioned in the above figure, for CIS to process AS3 ConfigMap, ensure that below AS3 labels are populated.

Label Value Description
as3 true (or) false When set to true, this tells CIS that this is a AS3 ConfigMap and processes it. When set to false, this tells the CIS that you don’t want to usee AS3 ConfigMap, meaning you do not want CIS to process this ConfigMap temporarily until you reset this flag to true. If AS3 ConfigMap exists with flag flase, CIS will remove the respective configuration from BIG-IP. Meanwhile, you can make the necessary changes and save the ConfigMap within the K8S system.
f5type virtual-server This tells the CIS that you want to create a virtual server on the BIG-IP device.

Important

Staging is not equivalent to deleting ConfigMap in CIS. CIS will save the previous active copy of ConfigMap before the ConfigMap AS3 label was set to false.

Note

Along with the above labels, to process an AS3 declaration, CIS uses goJsonSchema to validate AS3 declarations. If the JSON data structure does not conform with the schema, an error is logged.

To process AS3 ConfigMap, the highlighted CIS deployment configurations are required.

Highlighted CIS deployment configurations are required
1
2
3
4
5
6
7
   args: [
   "--bigip-username=$(BIGIP_USERNAME)",
   "--bigip-password=$(BIGIP_PASSWORD)",
   "--bigip-url=10.10.10.10",
   "--bigip-partition=CIS-Partition",
   "--pool-member-type=cluster",
   ]

How to deploy ConfigMap

Prerequisites

  • CIS version 2.0 or newer
  • CIS uses AS3 declarative API. You will need the AS3 extension v3.18 or newer installed on BIG-IP before using the AS3 extension of CIS.

You can find the required YAML files in the respository on GitHub.

CIS uses the partition defined in the CIS configuration by default to communicate with the BIG-IP system when adding static ARPs and forwarding entries for VXLAN. CIS managed partitions <partition> and should not be used in ConfigMap as tenants. If CIS is deployed with --bigip-partition=cis, then <cis> and is not supposed to be used as a tenant in the AS3 declaration.

CIS Service Discovery

This procedural diagram depicts Service Discovery while processing ConfigMap in CIS:

../_images/config-map-diagram-quickstart1.png

Important

From the above figure, for ConfigMap to properly function in CIS, configure the same tenant, application, and pool details for steps 1 and 3.

  1. Prepare and deploy the desired service (Nodeport in this example) in Kubernetes. Make sure the below labels are configured:
    • cis.f5.com/as3-tenant: Tenant-1
    • cis.f5.com/as3-app: APP1
    • cis.f5.com/as3-pool: web_pool
  2. Prepare and deploy the backend application deployment that is going to be served by BIG-IP.
  3. Prepare and deploy the AS3 deployment inside an AS3 ConfigMap template in Kubernetes. Make sure the tenant, application, and pools are configured with the same values as in Step 1.
    • Tenant Class: Tenant-1
    • Application Class: APP1
    • Pool Class:  web_pool
  4. After the AS3 ConfigMap becomes available for processing, CIS decodes the AS3 declaration and extracts tenant (Tenant-1), Application (APP1) and Pool (web_pool) details.
  5. CIS performs service discovery using extracted tenant (Tenant-1), Application (APP1) and Pool (web_pool) details, and fetches service endpoints, in this example 10.105.126.114:80.
  6. After completing Service discovery, CIS modifies the AS3 declaration by appending the discovered endpoints. CIS only modifies these two values in the AS3 declaration:
    • serverAddresses array
    • servicePort value
  7. CIS posts the generated AS3 declaration to the BIG-IP system to begin processing traffic.

Important

From the above figure, for ConfigMap to properly function in CIS, configure the same tenant, application, and pool details for step 1 and step 3.

Supported operations of AS3 ConfigMap in CIS

CIS processes when a ConfigMap is created, modified, or deleted in Kubernetes.

The sections below explain the detailed operations of AS3 ConfigMap in CIS for creation, modification, and deletion.

Create AS3 ConfigMap

This section uses the command $ kubectl apply -f <as3_configmap_file_in_yaml> to create ConfigMap.

There are three other ways to create ConfigMap by using the kubectl create configmap command:

  • Use the contents of an entire directory:
$  kubectl create configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl create configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart2.png

  1. Submit the Ingress resource, and deploy it in Kubernetes.
  2. CIS processes the Ingress resource, saves Ingress context, and sends the AS3 Declaration to BIG-IP to begin processing traffic.
  3. Prepare and deploy the AS3 deployment inside an AS3 ConfigMap template.
  4. After the AS3 ConfigMap becomes available for processing, CIS performs AS3 Validation followed by service discovery as described in the Service Discovery section.
  5. After completing Service Discovery, CIS modifies the AS3 declaration by appending the discovered endpoints to it.
  6. CIS posts the generated AS3 declaration to BIG-IP to begin processing traffic.

Now you will be able to see the BIG-IP objects under partition (Tenant-1) along with CIS Managed Partition (CIS-Partition).

Modify AS3 ConfigMap

This section uses the command $ kubectl apply -f <as3_configmap_file_in_yaml> to Modify ConfigMap.

There are three other ways to modify ConfigMap by using the “kubectl apply configmap” command:

  • Use the contents of an entire directory:
$  kubectl apply configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl apply configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl apply configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart3.png

This example uses ConfigMap with multiple tenants (Tenant-1, Tenant-2, and Tenant-3)

  1. Submit the multiple tenant AS3 template inside the AS3 ConfigMap, and deploy it in Kubernetes.
  2. After the AS3 ConfigMap becomes available for processing, CIS performs Service Discovery.
  3. After Service Discovery, CIS modifies the AS3 declaration by appending the discovered endpoints to it.
  4. CIS posts the generated AS3 declaration to BIG-IP to begin processing traffic. You will be able to see the BIG-IP objects under partitions (Tenant-1, Tenant-2, and Tenant-3).
  5. Modify Tenant-3 objects in ConfigMap and deploy them in Kubernetes.
  6. After the modified AS3 ConfigMap becomes available for processing, CIS again performs validation and service discovery procedures.
  7. After Service Discovery, CIS modifies the AS3 declaration by appending the discovered endpoints to it and posts the generated AS3 declaration to the BIG-IP system to begin processing traffic.

Along with modified objects in Tenant-3, you will be able to see the BIG-IP objects under partition (Tenant-1 and Tenant-2).

The diagram below is the continuation of ConfigMap Modification. In this case, you will understand the procedure when one of the Tenants is removed in the ConfigMap’s AS3 Declaration.

This operation is still a modify operation on ConfigMap but results in the deletion of AS3 partition in BIG-IP.

../_images/config-map-diagram-quickstart4.png
  1. Modify ConfigMap by removing the Tenant-2 section in ConfigMap and deploy them in Kubernetes.
  2. After the modified AS3 ConfigMap becomes available for processing, CIS again performs validation and service discovery procedures.
  3. After completion of Service discovery, CIS deletes the Tenant-2 partition by posting delete partition request to BIG-IP.

After CIS processes the modification of ConfigMap, you can see the BIG-IP objects under partitions Tenant-1 and Tenant-3 only.

Delete AS3 ConfigMap

This section uses the command $ kubectl delete -f <as3_configmap_file_in_yaml> to Delete ConfigMap.

There are three other ways to delete ConfigMap by using the kubectl delete configmap command:

  • Use the contents of an entire directory:
$  kubectl delete configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl delete configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl delete configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart5.png
  1. Submit the AS3 template inside the AS3 ConfigMap, and deploy it in Kubernetes.
  2. After the AS3 ConfigMap becomes available for processing, CIS performs service discovery.
  3. CIS modifies the AS3 template, appends the discovered endpoints, and posts the AS3 declaration to the BIG-IP system to begin processing traffic.
  4. Perform delete ConfigMap operation in Kubernetes.
  5. CIS receives the delete ConfigMap request through ConfigMap informers.
  6. CIS sends the delete ConfigMap partition request to BIG-IP.
  7. BIG-IP removes the associated ConfigMap partition and cleans up its Data Path.

Override AS3 ConfigMap

The Override AS3 ConfigMap hosts a part of AS3 as a configuration to be overridden. Using this ConfigMap, CIS implements the AS3 override functionality.

AS3 override functionality allows users to alter the existing BIG-IP configuration using AS3 with a ConfigMap without affecting the existing Kubernetes resources. The administrator can modify the existing BIG-IP configuration incrementally without having to overwrite/delete the existing one.

Important

Override functionality can be applied only on Routes or Ingress resources, but not on AS3 ConfigMap. This also means that the scope of override functionality is limited to CIS-managed partitions in BIG-IP.

In order to deploy override AS3 ConfigMap, you will need to add a new argument to the deployment file. Apply the following optional configuration on CIS deployment to enable AS3 override functionality:

--override-as3-declaration=<namespace>/<as3_configmap_name>
args: [
"--bigip-username=$(BIGIP_USERNAME)",
"--bigip-password=$(BIGIP_PASSWORD)",
"--bigip-url=10.10.10.10",
"--bigip-partition=CIS-Partition",
"--pool-member-type=cluster",

"--as3-validation=true"

"--override-as3-declaration=default/cm227"

]

CIS can still process override AS3 ConfigMap, even though this configuration is not present. It is the responsibility of the user to always maintain a single valid AS3 Override ConfigMap in the system to avoid discrepancies.

Warning

When CIS is configured without the --override-as3-declaration option, and if more than one override AS3 ConfigMap is present, CIS will throw an error, and behavior can be unpredictable.

How to apply override functionality on an AS3 Declaration

AS3 override cannot be applied to all of the objects in the AS3 declaration, only the components under the Tenant Class section should be overridden in CIS.

The image below depicts the scope of override AS3 declarations in CIS. Blocks in blue are only allowed to override:

../_images/config-map-diagram-quickstart6.png

Warning

From the above figure, you should only override the configuration in blue blocks. CIS does not prevent you from overriding the configuration of other blocks like AS3 Class or ADC Class.

../_images/config-map-diagram-quickstart7.png

How to deploy Override AS3 ConfigMap

CIS processes when Override AS3 ConfigMap is created, modified, or deleted in Kubernetes.

Example Override AS3 ConfigMap
   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: example-vs
     namespace: default
   labels:
      f5type: virtual-server
      overrideAS3: "true"
   data:
   template: |
      {
         "declaration": {
               "test_AS3": {
                  "Shared": {
                     "ingress_172_16_3_23_80": {
                           "virtualAddresses": [
                              "172.16.3.111"
                           ]
                     }
                  }
               }
         }
      }

Create Override AS3 ConfigMap

This section uses the command $ kubectl apply -f <override_as3_configmap_file_in_yaml> to Create ConfigMap.

There are three other ways to create ConfigMap by using the kubectl create configmap command:

  • Use the contents of an entire directory:
$  kubectl create configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl create configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart8.png

  1. Submit the Ingress resource, and deploy it in Kubernetes.

    ../_images/config-map-diagram-quickstart9.png

    Later sections show how to change the virtual server address with AS3 override functionality. In the above screenshot, you can see a virtual server ingress_172_16_3_23_80 and the destination IP 172.16.3.23.

  2. CIS will process the Ingress resource, save Ingress context, and send the AS3 declaration to BIG-IP to begin processing traffic.

  3. Prepare and deploy the AS3 deployment inside an Override AS3 ConfigMap template.

  4. After the Override AS3 ConfigMap becomes available for processing, CIS performs the AS3 Override operation on the saved Ingress AS3 declaration.

  5. CIS will post the Overriden AS3 declaration to BIG-IP.

Now you can see the BIG-IP objects with Virtual being overridden under partition (test_AS3).

../_images/config-map-diagram-quickstart10.png

Modify Override AS3 ConfigMap

This section uses the command $ kubectl apply -f <override_as3_config_map_file_in_yaml> to Modify ConfigMap.

There are three other ways to modify ConfigMap by using the kubectl apply configmap command:

  • Use the contents of an entire directory:
$  kubectl apply configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl apply configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl apply configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart11.png

This is the continuation of the previous Create Override ConfigMap.

  1. After the successful creation of Override ConfigMap, CIS will save and manage the Override AS3 declaration along with Ingress AS3 Declaration.
  2. Modify the Virtual address to the new value as mentioned in the above figure.
  3. CIS will verify and save the Override AS3 ConfigMap when available for processing.
  4. CIS performs AS3 Override operation on the saved Ingress AS3 declaration and posts the Overriden AS3 declaration to the BIG-IP.

Delete Override AS3 ConfigMap

This section uses the command $ kubectl delete -f <as3_configmap_file_in_yaml> to Delete ConfigMap.

There are three other ways to delete ConfigMap by using the kubectl delete configmap command:

  • Use the contents of an entire directory:
$  kubectl delete configmap my-config --from-file=./my/dir/path/
  • Use the contents of a file or specific set of files:
$ kubectl apply configmap my-config --from-file=./my/file_name.json
  • Use literal key-value pairs defined on the command line:
$ kubectl apply configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
../_images/config-map-diagram-quickstart12.png

This is the continuation of the previous Modify Override ConfigMap.

  1. After the successful modification of Override ConfigMap, CIS will save and manage the modified AS3 declaration along with ingress AS3 Declaration.
  2. Delete the Override ConfigMap from Kubernetes.
  3. CIS will receive the delete ConfigMap request and remove the Override ConfigMap AS3 declaration context from CIS.
  4. CIS finds there is no override AS3 declaration to override saved Ingress AS3 Declaration, so it will send the Ingress AS3 declaration as is.

Now you will see the Ingress specific Virtual address that was configured on the BIG-IP.

../_images/config-map-diagram-quickstart13.png

Repository


Note

To provide feedback on Container Ingress Services or this documentation, you can file a GitHub Issue.