From 881ca3d006ae85bdd51f3890e176353de8346d48 Mon Sep 17 00:00:00 2001 From: Jeff Geerling Date: Mon, 29 Jun 2020 16:25:42 -0500 Subject: [PATCH] Fixes #145: Use FQCN in module docs and in plugin examples. --- README.md | 74 +++++++++++-------- plugins/inventory/k8s.py | 6 +- plugins/inventory/openshift.py | 6 +- plugins/lookup/k8s.py | 14 ++-- plugins/modules/k8s.py | 2 +- plugins/modules/k8s_info.py | 10 +-- .../kubernetes/library/test_tempfile.py | 4 +- 7 files changed, 66 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 470c28c0..04120934 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,51 @@ Content in this collection requires the [OpenShift Python client](https://pypi.o ### Using modules from the Kubernetes Collection in your playbooks -You can either call modules by their Fully Qualified Collection Namespace (FQCN), like `community.kubernetes.k8s_info`, or you can call modules by their short name if you list the `community.kubernetes` collection in the playbook's `collections`, like so: +It's preferable to use content in this collection using their Fully Qualified Collection Namespace (FQCN), for example `community.kubernetes.k8s_info`: + +```yaml +--- +- hosts: localhost + gather_facts: false + connection: local + + tasks: + - name: Ensure the myapp Namespace exists. + community.kubernetes.k8s: + api_version: v1 + kind: Namespace + name: myapp + state: present + + - name: Ensure the myapp Service exists in the myapp Namespace. + community.kubernetes.k8s: + state: present + definition: + apiVersion: v1 + kind: Service + metadata: + name: myapp + namespace: myapp + spec: + type: LoadBalancer + ports: + - port: 8080 + targetPort: 8080 + selector: + app: myapp + + - name: Get a list of all Services in the myapp namespace. + community.kubernetes.k8s_info: + kind: Service + namespace: myapp + register: myapp_services + + - name: Display number of Services in the myapp namespace. + debug: + var: myapp_services.resources | count +``` + +If upgrading older playbooks which were built prior to Ansible 2.10 and this collection's existence, you can also define `collections` in your play and refer to this collection's modules as you did in Ansible 2.9 and below, as in this example: ```yaml --- @@ -74,34 +118,6 @@ You can either call modules by their Fully Qualified Collection Namespace (FQCN) kind: Namespace name: myapp state: present - - - name: Ensure the myapp Service exists in the myapp Namespace. - k8s: - state: present - definition: - apiVersion: v1 - kind: Service - metadata: - name: myapp - namespace: myapp - spec: - type: LoadBalancer - ports: - - port: 8080 - targetPort: 8080 - selector: - app: myapp - - - name: Get a list of all Services in the myapp namespace. - k8s_info: - kind: Service - namespace: myapp - register: myapp_services - - - name: Display number of Services in the myapp namespace. - debug: - var: myapp_services.resources | count - ``` For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README. diff --git a/plugins/inventory/k8s.py b/plugins/inventory/k8s.py index 9c314562..d2bbc3fb 100644 --- a/plugins/inventory/k8s.py +++ b/plugins/inventory/k8s.py @@ -94,20 +94,20 @@ EXAMPLES = ''' # File must be named k8s.yaml or k8s.yml # Authenticate with token, and return all pods and services for all namespaces -plugin: k8s +plugin: community.kubernetes.k8s connections: - host: https://192.168.64.4:8443 api_key: xxxxxxxxxxxxxxxx validate_certs: false # Use default config (~/.kube/config) file and active context, and return objects for a specific namespace -plugin: k8s +plugin: community.kubernetes.k8s connections: - namespaces: - testing # Use a custom config file, and a specific context. -plugin: k8s +plugin: community.kubernetes.k8s connections: - kubeconfig: /path/to/config context: 'awx/192-168-64-4:8443/developer' diff --git a/plugins/inventory/openshift.py b/plugins/inventory/openshift.py index bdd63406..f6c393bd 100644 --- a/plugins/inventory/openshift.py +++ b/plugins/inventory/openshift.py @@ -94,20 +94,20 @@ EXAMPLES = ''' # File must be named openshift.yaml or openshift.yml # Authenticate with token, and return all pods and services for all namespaces -plugin: openshift +plugin: community.kubernetes.openshift connections: - host: https://192.168.64.4:8443 api_key: xxxxxxxxxxxxxxxx verify_ssl: false # Use default config (~/.kube/config) file and active context, and return objects for a specific namespace -plugin: openshift +plugin: community.kubernetes.openshift connections: - namespaces: - testing # Use a custom config file, and a specific context. -plugin: openshift +plugin: community.kubernetes.openshift connections: - kubeconfig: /path/to/config context: 'awx/192-168-64-4:8443/developer' diff --git a/plugins/lookup/k8s.py b/plugins/lookup/k8s.py index 68fa9df5..68849053 100644 --- a/plugins/lookup/k8s.py +++ b/plugins/lookup/k8s.py @@ -133,23 +133,23 @@ DOCUMENTATION = ''' EXAMPLES = """ - name: Fetch a list of namespaces set_fact: - projects: "{{ lookup('k8s', api_version='v1', kind='Namespace') }}" + projects: "{{ lookup('community.kubernetes.k8s', api_version='v1', kind='Namespace') }}" - name: Fetch all deployments set_fact: - deployments: "{{ lookup('k8s', kind='Deployment') }}" + deployments: "{{ lookup('community.kubernetes.k8s', kind='Deployment') }}" - name: Fetch all deployments in a namespace set_fact: - deployments: "{{ lookup('k8s', kind='Deployment', namespace='testing') }}" + deployments: "{{ lookup('community.kubernetes.k8s', kind='Deployment', namespace='testing') }}" - name: Fetch a specific deployment by name set_fact: - deployments: "{{ lookup('k8s', kind='Deployment', namespace='testing', resource_name='elastic') }}" + deployments: "{{ lookup('community.kubernetes.k8s', kind='Deployment', namespace='testing', resource_name='elastic') }}" - name: Fetch with label selector set_fact: - service: "{{ lookup('k8s', kind='Service', label_selector='app=galaxy') }}" + service: "{{ lookup('community.kubernetes.k8s', kind='Service', label_selector='app=galaxy') }}" # Use parameters from a YAML config @@ -159,11 +159,11 @@ EXAMPLES = """ - name: Using the config (loaded from a file in prior task), fetch the latest version of the object set_fact: - service: "{{ lookup('k8s', resource_definition=config) }}" + service: "{{ lookup('community.kubernetes.k8s', resource_definition=config) }}" - name: Use a config from the local filesystem set_fact: - service: "{{ lookup('k8s', src='service.yml') }}" + service: "{{ lookup('community.kubernetes.k8s', src='service.yml') }}" """ RETURN = """ diff --git a/plugins/modules/k8s.py b/plugins/modules/k8s.py index a02d3a8f..54eda719 100644 --- a/plugins/modules/k8s.py +++ b/plugins/modules/k8s.py @@ -24,7 +24,7 @@ description: - Pass the object definition from a source file or inline. See examples for reading files and using Jinja templates or vault-encrypted files. - Access to the full range of K8s APIs. - - Use the M(k8s_info) module to obtain a list of items about an object of type C(kind) + - Use the M(community.kubernetes.k8s_info) module to obtain a list of items about an object of type C(kind) - Authenticate using either a config file, certificates, password or token. - Supports check mode. diff --git a/plugins/modules/k8s_info.py b/plugins/modules/k8s_info.py index a4b2715b..9d598c1c 100644 --- a/plugins/modules/k8s_info.py +++ b/plugins/modules/k8s_info.py @@ -70,7 +70,7 @@ requirements: EXAMPLES = r''' - name: Get an existing Service object - k8s_info: + community.kubernetes.k8s_info: api_version: v1 kind: Service name: web @@ -78,26 +78,26 @@ EXAMPLES = r''' register: web_service - name: Get a list of all service objects - k8s_info: + community.kubernetes.k8s_info: api_version: v1 kind: Service namespace: testing register: service_list - name: Get a list of all pods from any namespace - k8s_info: + community.kubernetes.k8s_info: kind: Pod register: pod_list - name: Search for all Pods labelled app=web - k8s_info: + community.kubernetes.k8s_info: kind: Pod label_selectors: - app = web - tier in (dev, test) - name: Search for all running pods - k8s_info: + community.kubernetes.k8s_info: kind: Pod field_selectors: - status.phase=Running diff --git a/tests/integration/targets/kubernetes/library/test_tempfile.py b/tests/integration/targets/kubernetes/library/test_tempfile.py index c56377c0..c89f5a31 100644 --- a/tests/integration/targets/kubernetes/library/test_tempfile.py +++ b/tests/integration/targets/kubernetes/library/test_tempfile.py @@ -18,8 +18,8 @@ short_description: Creates temporary files and directories description: - The C(test_tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible - you need to use M(file) module. - - For Windows targets, use the M(win_tempfile) module instead. + you need to use M(ansible.builtin.file) module. + - For Windows targets, use the M(ansible.builtin.win_tempfile) module instead. options: state: