Merge pull request #146 from geerlingguy/145-fqcn

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

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.

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'

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'

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 = """

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.
 

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

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.
+    you need to use M(ansible.builtin.file) module.
-  - For Windows targets, use the M(win_tempfile) module instead.
+  - For Windows targets, use the M(ansible.builtin.win_tempfile) module instead.
 
 options:
   state: