search

ansible-collections / kubernetes.core

The collection includes a variety of Ansible content to help automate the management of applications in Kubernetes and OpenShift clusters, as well as the provisioning and maintenance of clusters themselves.
Other
214 stars 133 forks source link

Doc: add example of using kubectl connection plugin #741

Closed yurnov closed 3 months ago

yurnov commented 4 months ago
SUMMARY

Currently documentation for collection don't include any examples of using kubenrenes.core.kubectl connection plugin and it's hard to start using that plugin.

ISSUE TYPE
COMPONENT NAME

kubenrenes.core.kubectl connection plugin

ADDITIONAL INFORMATION

This PR was inspired by #288 and based on feedback on that PR and my own experience. Thanks @tpo for his try and @geerlingguy for his Ansible for DevOps book

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/e6f1c382fb0d4b348c5fc9debdefc7de

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 3m 32s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 47s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/818d96ca3fc1495f89e6b1ffc382e3dc

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 45s

tpo commented 4 months ago

Terrific improvement of the documentation. Thanks a lot @yurnov ! I have reviewed the changes and hope this can be merged.

In case there is a formal flag "reviewed by tpo" or such then I could add it if someone could point me to what the syntax is.

yurnov commented 4 months ago

Hi @abikouo and @gravesm,

Can this PR be merged and backported to the stable-3... stable-5 branches? The request to backport to stable-3 and release some 3.2 or so is related to the fact that major version 4 is not included in Ansible 10 which means that documentation changes for collection version 4.x.x and 5.x.x. will not be part of official ansible documentation for another 6+ months.

Based on Ansible Project 10, the current stable version is an Ansible 9 (which include kubernetes.core version 2.4.2) and Ansible 10 should be released tomorrow or in the next week and that version will consist of collection version 3.1.0

yurnov commented 4 months ago

Just minor remarks regarding FQCN and naming playbooks

Thanks, your comments was considered

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/6aba9a67debb44ee9f3ea62be5475fda

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 57s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 00s

gravesm commented 4 months ago

Also, I'm unsure where any of the docs in the /docs directory here ever show up for users. They don't show up on Galaxy or docs.ansible.com. That's a broader issue than this PR but something to investigate. My limited knowledge of Galaxy/AH says files directly in the /docs directory must be .md not rst. And docs for docs.ansible.com must be in docs/docsite/rst.

@samccann We use https://github.com/ansible-network/collection_prep to generate docs. I believe this is done solely so there are docs on GH. I assume the release pipeline has its own docs build step, but I'm not sure. The docs for this plugin do show up on https://docs.ansible.com/ansible/latest/collections/kubernetes/core/kubectl_connection.html#ansible-collections-kubernetes-core-kubectl-connection.

samccann commented 4 months ago

@samccann We use https://github.com/ansible-network/collection_prep to generate docs. I believe this is done solely so there are docs on GH. I assume the release pipeline has its own docs build step, but I'm not sure. The docs for this plugin do show up on https://docs.ansible.com/ansible/latest/collections/kubernetes/core/kubectl_connection.html#ansible-collections-kubernetes-core-kubectl-connection.

Ah thanks for the clarification. I saw the files but didn't put 2+2 together and realize they were just a local copy (in GH) of the module docs.

yurnov commented 4 months ago

Also, I'm unsure where any of the docs in the /docs directory here ever show up for users.

I'm not sure how a ansible site shown docs, but in any case, they generated from DOCUMENTATION and EXAMPLES in the Python code by the https://github.com/ansible-network/collection_prep, as mentioned in CONTRIBUTING.

It looks like they are combined from the rst fragments.

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/06fd3d2f9e514e9bbdf860d0098fb9d9

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 49s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 52s

softwarefactory-project-zuul[bot] commented 4 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/87b60aa4e5c047d59f7323ae9bb98ff6

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 4m 08s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 10s

softwarefactory-project-zuul[bot] commented 3 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/759ed17d615f4d0fb091b10f23e67bd1

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 3m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 09s

softwarefactory-project-zuul[bot] commented 3 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/3ba6817eb3c54141b56daa48f2ebdf05

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 09s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 49s

softwarefactory-project-zuul[bot] commented 3 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/d88a950781e24bf08cf718983718cc56

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 3m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 57s

yurnov commented 3 months ago

Hi @gravesm @abikouo,

somehow linter started to fail on example. I considered adding changed_when: false (please find the commit 03be82d2a2d11fb358bc38cd991632e9bdec6645), but some users might assume that you have to use changed_when: false

So, I decided (actually, it was recommended by @felixfontein in community:ansible.com matrix channel to add rule no-changed-when to ignore list. Do you ok with that?

softwarefactory-project-zuul[bot] commented 3 months ago

Build succeeded. https://ansible.softwarefactory-project.io/zuul/buildset/3b21aec678bf43ec9ae1243aeff1388c

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 3m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 8m 26s

softwarefactory-project-zuul[bot] commented 3 months ago

Build succeeded (gate pipeline). https://ansible.softwarefactory-project.io/zuul/buildset/c6a2f2f6a7374c9d92cd11fcc7015ab7

:heavy_check_mark: ansible-galaxy-importer SUCCESS in 5m 23s :heavy_check_mark: build-ansible-collection SUCCESS in 7m 56s

patchback[bot] commented 3 months ago

Backport to stable-3: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-3/fb80d973c446d6626aa00a0f55a8ae53e3e517c4/pr-741

Backported as https://github.com/ansible-collections/kubernetes.core/pull/743

🤖 @patchback I'm built with octomachinery and my source is open — https://github.com/sanitizers/patchback-github-app.

patchback[bot] commented 3 months ago

Backport to stable-5: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-5/fb80d973c446d6626aa00a0f55a8ae53e3e517c4/pr-741

Backported as https://github.com/ansible-collections/kubernetes.core/pull/744

🤖 @patchback I'm built with octomachinery and my source is open — https://github.com/sanitizers/patchback-github-app.

yurnov commented 3 months ago

Thanks @gravesm!