Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/redhat-cop/k8s_config

Ansible role for managing Kubernetes configuration
https://github.com/redhat-cop/k8s_config

gpte

Last synced: 4 months ago
JSON representation

Ansible role for managing Kubernetes configuration

Awesome Lists containing this project

README 

          
:toc:

:toc-placement!:



= k8s_config



Ansible role for managing Kubernetes configuration



toc::[]



== 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 https://docs.ansible.com/ansible/latest/modules/k8s_info_module.html[k8s_info] module.

Must specify `api_version` and `kind` and may also specify `name` and `namespace`.



* `json_patch` - https://jsonpatch.com/[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: git@github.com: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