Config Map

What is Config Map

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 operate 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 below two types of AS3 Config Maps, 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 user-defined AS3 ConfigMap

The user-defined 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 user-defined 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 user-defined AS3 ConfigMap can have more than one partition, except CIS-managed partition. CIS will not process user-defined AS3 ConfigMap if configured in CIS-managed partition.

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

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

How to deploy Config map

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 Service Discovery

Below procedural diagram depicts the Service Discovery while processing user-defined 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: AS3
    • cis.f5.com/as3-app: APP1
    • cis.f5.com/as3-pool: web_pool
  2. Prepare and deploy backend application deployment that is going to be served by BIG-IP.
  3. Prepare and deploy the AS3 deployment inside a user-defined AS3 ConfigMap template in Kubernetes. Make sure the tenant, application, and pools are configured with the same values as in Step 1.
    • Tenant Class:  AS3
    • Application Class:  APP1
    • Pool Class:  web_pool
  4. After the user-defined AS3 configMap becomes available for processing, CIS will decode the AS3 declaration and extract tenant (Tenant-1), Application (APP1) and Pool (web_pool) details.
  5. CIS performs service discovery using extracted tenant (AS3), Application (APP1) and Pool (web_pool) details, and fetch service endpoints, in this example 10.105.126.114:80.
  6. After completion of Service discovery, CIS modifies the AS3 declaration by appending the discovered endpoints. CIS only modify 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

Supported operations of user-defined AS3 ConfigMap in CIS

CIS Processes when a user-defined ConfigMap is created or modified or deleted in Kubernetes.

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

Create a user-defined AS3 ConfigMap

This section uses the command $ kubectl apply -f <user_defined_config_map_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. CIS will process the Ingress resource and save Ingress context and send the AS3 Declaration to BIG-IP to begin processing traffic.
  2. Prepare and deploy the AS3 deployment inside a user-defined AS3 ConfigMap template.
  3. After the user-defined AS3 configMap becomes available for processing, CIS performs AS3 Validation followed by service discovery as described in the Service Discovery section.
  4. After completion of Service discovery, CIS modifies the AS3 declaration by appending the discovered endpoints to it.
  5. CIS posts the generated AS3 declaration to BIG-IP to begin processing traffic.
  6. Now you will be able to see the BIG-IP objects under partition(Tenant-1) along with CIS Managed Partition(CIS-Partition).

Modify a user-defined AS3 ConfigMap

This section uses the command $ kubectl apply -f <user_defined_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-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 user-defined AS3 configMap, and deploy it in Kubernetes.
  2. After the user-defined 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, now 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 user-defined 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 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 user-defined 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 will be able to see the BIG-IP objects under partitions Tenant-1 and Tenant-3 only.

Delete a user-defined AS3 ConfigMap

This section uses the command $ kubectl delete -f <user_defined_config_map_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 multiple tenant AS3 template inside the user-defined AS3 configMap, and deploy it in Kubernetes.
  2. After the user-defined AS3 configMap becomes available for processing, CIS performs service discovery.
  3. After Service discovery, CIS modifies the AS3 template and appends the discovered endpoints.
  4. CIS posts the generated AS3 declaration to the BIG-IP system to begin processing traffic.

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 user-defined AS3 ConfigMap. This also means that the scope of override functionality is limited to CIS managed partition 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>/<user_defined_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 declaration 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 Config map

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

  1. CIS will process the Ingress resource, save Ingress context, and send the AS3 declaration to BIG-IP to begin processing traffic.
  2. Prepare and deploy the AS3 deployment inside an Override AS3 ConfigMap template.
  3. After the Override AS3 configMap becomes available for processing, CIS performs AS3 Override operation on the saved Ingress AS3 declaration.
  4. CSI will post the Overriden AS3 declaration to BIG-IP.

Now you will be able to 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 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-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. Now modify the Virtual address to 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 <user_defined_config_map_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

Staging ConfigMap in CIS

Staging is a feature introduced in CIS 2.0. This feature if enabled, allows you to stop the processing of any new changes to ConfigMap in CIS. Changes can be applied back to CIS once this feature is disabled.

This feature gives you the flexibility to verify or validate the Configmap locally before submitting it in critical production environments.

Changes can be applied once the Staging feature is reset. This feature can be managed through as3 label in ConfigMap Metadata.

  • When Label as3 = false, staging is enabled in CIS, and CIS will discard subsequent ConfigMap changes.
  • When Label as3 = true, staging is disabled in CIS and now CIS will honor the changes to ConfigMap.

Important

Staging in CIS is not equivalent to deleting ConfigMap. CIS will store and maintain the last modified ConfigMaps’s AS3 declaration before the Staging is enabled to ConfigMap.

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

The above staging functionality also applies to Override AS3 ConfigMap. In this case when staging is applied, subsequent changes to Override AS3 ConfigMap will be discarded in CIS, and the changes will only be applied once ConfigMap is un-staged.

  1. Submit the AS3 template inside the user-defined AS3 configMap, and deploy it in Kubernetes.
  2. After the user-defined AS3 configMap becomes available for processing, CIS performs service discovery.
  3. After Service discovery completes, CIS modifies the AS3 template and appends the discovered endpoints. CIS posts the generated AS3 declaration to the BIG-IP system to begin processing traffic.
  4. Stage the ConfigMap by changing the as3 label from true to false, and submit it in Kubernetes.
  5. The changes are discarded by CIS and all subsequent modifications on this ConfigMap will be discarded, but the previous ConfigMap context will be still saved in CIS.
  6. Un-Stage the ConfigMap by changing the as3 label back to true from false, and submit it in Kubernetes.

#. The changes are honored by CIS and the last modified ConfigMap template changes will be applied to the AS3 Declaration. CIS will now post the modified AS3 declaration to BIG-IP.

Warning

Delete operation on ConfigMap will also be discarded in CIS when Staging is configured. If you want to delete the ConfigMap, then you should unstage the ConfigMap and perform delete on ConfigMap.


Repository


Note

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