k8s_config

Ansible role for managing Kubernetes configuration

Table of Contents

• Requirements
• Installation
• Role Variables
  • Authentication Variables
  • Configuration Variables
  • Multi-cluster Support
• Example Playbooks
  • Configuration through variables:
  • Local Configuration
  • Multiple Configuration Sources
• License
• Author Information

Requirements

Ansible 2.9+

k8s module support

Installation

Install with ansible-galaxy:

ansible-galaxy install redhat-cop.k8s_config

Or install directly from GitHub:

ansible-galaxy install git+https://github.com/redhat-cop/k8s_config.git

Role Variables

Kubernetes configuration is specified through role variables. These variables can be stored in the ansible inventory or dynamically loaded with include_vars and other methods provided by ansible.

Authentication Variables

The following variables are provided for cluster authentication. If the host kubeconfig is already authenticated to the target cluster then no authentication variables are required.

These variables map to parameters of the k8s and k8s_info modules.

• k8s_api_ca_cert - Maps to ca_cert, which is the certificate provided to identify the client to the server when client_cert is also provided.

• k8s_api_client_cert - Maps to client_cert.

• k8s_api_client_key - Maps to client_key.

• k8s_api_token - Maps to api_key.

• k8s_api_url - Maps to host, which is the cluster API URL.

• k8s_api_validate_certs - Maps to validate_certs.

• k8s_kubeconfig - Maps to kubeconfig.

User and service account tokens are the preferred method of authentication for k8s_config, The parameters k8s_api_username and k8s_api_password may be provided to authenticate to the cluster API to receive a token which will then be used in subsequent API communication.

Configuration Variables

Configuration Sources

Configuration sources can be configured with k8s_config_sources. If provided, configuration sources will be used to load variables and be added to the search path for files and templates referended in k8s_config variables.

Settings for configuration sources:

• name - Source name, required.

• base_path - Base directory searched for configuration. If not provided then the root of the source git repository is used for git sources. Base path is optional for git config sources but required for local config sources.

• config_search_path - List of search paths relative to the base path used to find variables, files, and templates. The values in config_search_path are relative to base_path. If config_search_path is not given in k8s_config_sources then it can be provided by defining k8s_config_search_path in a main.yaml file located in the base path. If no search path is given or discovered, then the base path is added to the search path.

• git - Dictionary of parameters passed to the git module to clone the git repository. This should at least include repo. key_content is also supported which will dynamically write a temporary file for the SSH key and pass the path as key_file.

• when - Optional condition for loading configuration source. This can be useful to conditionally load a configuration source depending on whether credentials are available.

Cluster configuration

• k8s_resources - List of Kubernetes resource definitions. Resource definitions may be given as dictionaries described below. Namespaced resources given in this variables should include metadata.namespace.

• k8s_namespaces - Dictionary of Kubernetes namespaces and configuration to apply to the namespace. If a namespace does not exist then it will be created dynamically. OpenShift ProjectRequests are used to create namespace if direct creation is not permitted.

  • resources - List of Kubernetes resource definitions to apply to the namespace.

Resource Definitions:

Each resource definition is given as a dictionary. The presence of the key definition, file, helm_template, info, json_patch, namespace, openshift_template, or template determines how resource definitions are handled. Each resource item may also define register, until, retries, and delay which will then be applied to Ansible tasks run for these items.

Note

Due to limitations of Ansible, register actually sets non-cacheable host facts rather than true registered variables. Also, resource definition evaluation occurs in two passes, the first evaluation occurs before any items are processed and so references to registered variables must be protected with default filter or other methods to prevent undefined variable warnings. During the second pass of evaluation the registered values will be available and will be used in the actual application of the resource definition.

• namespace - Namespace specified within k8s_resources to provide ordering for namespace creation and resource provisioning.

• resources - Included with namespace, list of resources to provision into this namespace.

• action - Action to take with regard to resources when used with definition, file, helm_template, openshift_template or template. If k8s_config_action_override is defined then that value is used instead. If no action is specified then k8s_config_action_default is used, which defaults to apply. Value may be one of:

  • apply - Apply resource definitions to create or update resources in manner compatible with kubectl apply.

  • create - Create resources from definition only if resources do not exist.

  • delete - Delete resources from definition if it exists.

  • merge - Patch existing resources using merge strategy. If resources do not exist then attempt to create from definition.

  • replace - Create or replace resources.

  • strategic-merge - Patch existing resources using strategic-merge strategy. Automatically fall back to merge if strategic-merge is not supported. If resources do not exist then attempt to create from definition.

• when - All resources support use of when conditions to control processing. For example, a template may be conditionally processed depending on variables being set.

• definition - Direct resource definition within the Ansible variable:

  - name: ConfigMap for myconfig
    definition:
      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: myconfig
      data:
        hostname: k8s.example.com

• file - File lookup of resources. The value must be a file name which can be found in the Ansible file search path. Multiple resource definitions can be included in a single file by including a resource of kind v1/List and by including multiple YAML documents in the file.

  file: configmap.yaml

• helm_template - Helm template processing. Helm template can be specified with chart, git, dir, repo, values and version. If chart is specified then the chart will be looked up in a chart repository, configured with repo and version. git may provide a dictionary of parameters to pass to the git module and must at least specify repo. If git is provided then dir is the sub-directory within the repository holding the helm chart. If git is not provided then the value of dir will be searched for within any helm subdirectories within the k8s_config_search_path. Values for the helm chart may be passed as structured data with values. The helm command must be installed to process the template on the host.

  Example using a chart repository:

  helm_template:
    chart: cert-manager
    repo: https://charts.jetstack.io
    values:
      extraArgs:
      - --dns01-recursive-nameservers=1.1.1.1:53
      - --dns01-recursive-nameservers-only
      installCRDs: true
    version: v1.8.0

  Example using git:

  helm_template:
    git:
      repo: https://github.com/redhat-cop/anarchy.git
    dir: helm/
    values:
      replicaCount: 2

• openshift_template - OpenShift template file and parameters. The file can be specified with file or url. A dictionary, parameters is used for template parameters. A dictionary, env can be used similar to the oc new-app --env flag to set environment variables in container templates of generated resources. The oc command must be installed to process the template on the host.

  openshift_template:
    file: openshift-template.yaml
    parameters:
      NAME: myconfig
      HOSTNAME: k8s.example.com
    env:
      LOGLEVEL: debug

• template - Ansible Jinja2 template with file and variables. The template file must be a file name which can be found in the Ansible template search path. Variables provided are in addition to standard Ansible variables such as inventory host variables.

  template:
    file: configmap.yaml.j2
    vars:
      name: myconfig
      hostname: k8s.example.com

• info - Gather info using the Ansible k8s_info module. Must specify api_version and kind and may also specify name and namespace.

• json_patch - JSON patch to apply to resource. Must specify api_version, kind, name, and patch. The patch must be a valid JSON patch definition with the following adjustments to support idempotent patching of kubernetes resources:

  • remove operations are silently ignored when the path is not found in the resource definition.

  • add operations are silently ignored when the path is found with the specified value.

  • add operations may specify replace: false to produce an error if the path is set and is different from value.

  • test operations may specify state to define how the test value should be evaluated:

    • equal - the path value must equal the specified value, the default behavior.

    • unequal - the path value must not equal the specified value.

    • present - the path must be present with any value.

    • absent - the path must not be found in the resource.

  • test operations may specify operations as a list of operations to conditionally process if the test condition is true. If a test specifies operations then a failed test does not produce an error.

  • List indexes may be given with a simple key query of the form [?KEY=='VALUE'] to support for various kubernetes use cases where lists have name keys. The list index query resolves to - (end of list) if it fails to match when adding a value to a list.

  - name: Set ENV_LEVEL to dev for myapp
    json_patch:
      api_version: apps/v1
      kind: Deployment
      name: myapp
      patch:
      - op: add
        path: /spec/template/spec/containers/[?name=='myapp']/env/[?name=='ENV_LEVEL']/value
        value: dev

  - name: Set TEST if ENV_LEVEL is test
    json_patch:
      api_version: apps/v1
      kind: Deployment
      name: myapp
      patch:
      - op: test
        path: /spec/template/spec/containers/[?name=='myapp']/env/[?name=='ENV_LEVEL']/value
        value: test
        operations:
        - op: add
          path: /spec/template/spec/containers/[?name=='myapp']/env/[?name=='TEST']/value
          value: 'true'

Multi-cluster Support

The variable k8s_clusters can be set to configure multiple kubernetes clusters with a single role execution. k8s_clusters is given as a list of dictionaries. Each cluster dictionary may specify:

• api - API connection and authentication settings, including:

  • ca_cert - Cluster override for k8s_api_ca_cert

  • client_cert - Cluster override for k8s_api_client_cert

  • client_key - Cluster override for k8s_api_client_key

  • token - Cluster override for k8s_api_token

  • url - Cluster override for k8s_api_url

  • validate_certs - Cluster override for k8s_api_validate_certs

• namespaces - Cluster override for k8s_namespaces

• resources - Cluster override for k8s_resources

Example Playbooks

Configuration through variables:

Playbook:

- hosts: localhost
  gather_facts: false
  roles:
  - role: k8s_config
    vars:
      k8s_resources:
      - namespace: my-app
        resources:
        - name: App Config
          definition:
            apiVersion: v1
            kind: ConfigMap
            metadata:
              name: app-config
            data:
              envlevel: dev

Local Configuration

Playbook:

- hosts: localhost
  gather_facts: false
  roles:
  - role: k8s_config
    vars:
      k8s_config_sources:
      - name: local
        base_path "{{ playbook_dir }}/k8s-config"
      k8s_config_environment_level: dev

k8s-config/main.yaml

k8s_config_search_path:
- env/{{ k8s_config_environment_level }}
- common

k8s-config/env/dev/vars.yaml

myapp_image: example.com/myapp:latest
myapp_image_pull_policy: Always

k8s-config/common/vars.yaml

myapp_image: example.com/myapp:v0.1.2
myapp_image_pull_policy: IfNotPresent

k8s_resources:
- namespace: my-app
  resources:
  - name: App Config
    template:
      file: my-app-config.yaml.j2

k8s-config/common/templates/app-config.yaml.j2

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  envlevel: {{ k8s_config_environment_level | to_json }}

Multiple Configuration Sources

- hosts: localhost
  gather_facts: false
  roles:
  - role: k8s_config
    vars:
      k8s_config_sources:
      # Load config from k8s-config adjecent to playbook directory
      - name: local
        base_path: "{{ playbook_dir }}/k8s-config"

      # Load config from private git repository
      - name: private
        git:
          repo: [email protected]:example/k8s-config-private.git
          key_file: "{{ deploy_key }}"
        when: deploy_key != ''

      # ... and from public git repository
      - name: example
        git:
          repo: https://github.com/example/k8s-config.git

      # Override deploy_key with extra vars to use private repo
      deploy_key: ''

License

GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

Author Information

Johnathan Kupferer