Merge pull request #146 from geerlingguy/145-fqcn

Fixes #145: Use FQCN in module docs and in plugin examples.

README.md

@@ -56,27 +56,24 @@ 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
 
-  collections:
-    - community.kubernetes
-
   tasks:
     - name: Ensure the myapp Namespace exists.
-      k8s:
+      community.kubernetes.k8s:
         api_version: v1
         kind: Namespace
         name: myapp
         state: present
 
     - name: Ensure the myapp Service exists in the myapp Namespace.
-      k8s:
+      community.kubernetes.k8s:
         state: present
         definition:
           apiVersion: v1
@@ -93,15 +90,34 @@ You can either call modules by their Fully Qualified Collection Namespace (FQCN)
               app: myapp
 
     - name: Get a list of all Services in the myapp namespace.
-      k8s_info:
+      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
+---
+- hosts: localhost
+  gather_facts: false
+  connection: local
+
+  collections:
+    - community.kubernetes
+
+  tasks:
+    - name: Ensure the myapp Namespace exists.
+      k8s:
+        api_version: v1
+        kind: Namespace
+        name: myapp
+        state: present
 ```
 
 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.

plugins/inventory/k8s.py

@@ -94,20 +94,20 @@
 # 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'

plugins/inventory/openshift.py

@@ -94,20 +94,20 @@
 # 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'

plugins/lookup/k8s.py

@@ -133,23 +133,23 @@
 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 @@
 
 - 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 = """

plugins/modules/k8s.py

@@ -24,7 +24,7 @@
   - 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.
 

plugins/modules/k8s_info.py

@@ -70,34 +70,34 @@
 
 EXAMPLES = r'''
 - name: Get an existing Service object
-  k8s_info:
+  community.kubernetes.k8s_info:
     api_version: v1
     kind: Service
     name: web
     namespace: testing
   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

tests/integration/targets/kubernetes/library/test_tempfile.py

@@ -18,8 +18,8 @@
 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: