Ansible role for managing Kubernetes configuration
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
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.
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 toca_cert
, which is the certificate provided to identify the client to the server whenclient_cert
is also provided. -
k8s_api_client_cert
- Maps toclient_cert
. -
k8s_api_client_key
- Maps toclient_key
. -
k8s_api_token
- Maps toapi_key
. -
k8s_api_url
- Maps tohost
, which is the cluster API URL. -
k8s_api_validate_certs
- Maps tovalidate_certs
. -
k8s_kubeconfig
- Maps tokubeconfig
.
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 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 inconfig_search_path
are relative tobase_path
. Ifconfig_search_path
is not given ink8s_config_sources
then it can be provided by definingk8s_config_search_path
in amain.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 thegit
module to clone the git repository. This should at least includerepo
.key_content
is also supported which will dynamically write a temporary file for the SSH key and pass the path askey_file
. -
when
- Optional condition for loading configuration source. This can be useful to conditionally load a configuration source depending on whether credentials are available.
-
k8s_resources
- List of Kubernetes resource definitions. Resource definitions may be given as dictionaries described below. Namespaced resources given in this variables should includemetadata.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.
-
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 withink8s_resources
to provide ordering for namespace creation and resource provisioning. -
resources
- Included withnamespace
, list of resources to provision into this namespace. -
action
- Action to take with regard to resources when used withdefinition
,file
,helm_template
,openshift_template
ortemplate
. Ifk8s_config_action_override
is defined then that value is used instead. If noaction
is specified thenk8s_config_action_default
is used, which defaults toapply
. Value may be one of:-
apply
- Apply resource definitions to create or update resources in manner compatible withkubectl 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 tomerge
ifstrategic-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 kindv1/List
and by including multiple YAML documents in the file.file: configmap.yaml
-
helm_template
- Helm template processing. Helm template can be specified withgit
,dir
, andvalues
.git
may provide a dictionary of parameters to pass to thegit
module and must at least specifyrepo
. Ifgit
is provided thendir
is the sub-directory within the repository holding the helm chart. Ifgit
is not provided then the value ofdir
will be searched for within anyhelm
subdirectories within thek8s_config_search_path
. Values for the helm chart may be passed as structured data withvalues
. Thehelm
command must be installed to process the template on the host.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 withfile
orurl
. A dictionary,parameters
is used for template parameters. A dictionary,env
can be used similar to theoc new-app --env
flag to set environment variables in container templates of generated resources. Theoc
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 specifyapi_version
andkind
and may also specifyname
andnamespace
. -
json_patch
- JSON patch to apply to resource. Must specifyapi_version
,kind
,name
, andpatch
. 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 specifyreplace: false
to produce an error if the path is set and is different from value. -
test
operations may specifystate
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 specifyoperations
as a list of operations to conditionally process if the test condition is true. If a test specifiesoperations
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'
-
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 fork8s_api_ca_cert
-
client_cert
- Cluster override fork8s_api_client_cert
-
client_key
- Cluster override fork8s_api_client_key
-
token
- Cluster override fork8s_api_token
-
url
- Cluster override fork8s_api_url
-
validate_certs
- Cluster override fork8s_api_validate_certs
-
-
namespaces
- Cluster override fork8s_namespaces
-
resources
- Cluster override fork8s_resources
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
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 }}
- 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: ''
GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)