Doc: add example of using kubectl connection plugin #741

yurnov · 2024-06-01T14:50:51Z

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

Docs Pull Request

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 · 2024-06-01T15:17:16Z

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

✔️ ansible-galaxy-importer SUCCESS in 3m 32s
✔️ build-ansible-collection SUCCESS in 7m 47s

three hyphens as the berrinign of playbook in the example lead to "unparsable-with-libyaml: expected a single document in the stream - but found another document" error in yamllint, so three hyphens is removed in examples

softwarefactory-project-zuul · 2024-06-01T15:43:53Z

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

✔️ ansible-galaxy-importer SUCCESS in 4m 23s
✔️ build-ansible-collection SUCCESS in 7m 45s

tpo · 2024-06-02T10:41:22Z

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 · 2024-06-03T09:37:01Z

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

abikouo

Just minor remarks regarding FQCN and naming playbooks

changelogs/fragments/20240601-doc-example-of-using-kubectl.yaml

docs/kubernetes.core.kubectl_connection.rst

yurnov · 2024-06-03T11:12:40Z

Just minor remarks regarding FQCN and naming playbooks

Thanks, your comments was considered

comment intendation aligned

softwarefactory-project-zuul · 2024-06-03T11:30:11Z

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

✔️ ansible-galaxy-importer SUCCESS in 4m 57s
✔️ build-ansible-collection SUCCESS in 8m 00s

samccann

A few spelling fixes.

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.

docs/kubernetes.core.kubectl_connection.rst

plugins/connection/kubectl.py

gravesm · 2024-06-03T15:30:05Z

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 · 2024-06-03T15:49:24Z

@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 · 2024-06-03T16:05:45Z

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.

doc fragment (docs/kubernetes.core.kubectl_connection.rst) is generated by collection_prep_add_docs

softwarefactory-project-zuul · 2024-06-03T16:37:17Z

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

✔️ ansible-galaxy-importer SUCCESS in 4m 49s
✔️ build-ansible-collection SUCCESS in 7m 52s

softwarefactory-project-zuul · 2024-06-03T22:45:08Z

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

✔️ ansible-galaxy-importer SUCCESS in 4m 08s
✔️ build-ansible-collection SUCCESS in 8m 10s

purdzan

it seems typo

docs/kubernetes.core.kubectl_connection.rst

softwarefactory-project-zuul · 2024-06-05T13:16:05Z

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

✔️ ansible-galaxy-importer SUCCESS in 3m 23s
✔️ build-ansible-collection SUCCESS in 8m 09s

@felixfontein

it is recomendation by @felixfontein to avoid changed_when: false as it may confuse users and they mayht assume that you have to use that parameter most probably no-changed-when linter rule was enforced with ansible-lint v24.6.0 released yesterday https://github.com/ansible/ansible-lint/releases/tag/v24.6.0

softwarefactory-project-zuul · 2024-06-05T15:36:00Z

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

✔️ ansible-galaxy-importer SUCCESS in 5m 09s
✔️ build-ansible-collection SUCCESS in 7m 49s

and back echo "Hello, World"

softwarefactory-project-zuul · 2024-06-05T16:39:20Z

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

✔️ ansible-galaxy-importer SUCCESS in 3m 23s
✔️ build-ansible-collection SUCCESS in 7m 57s

yurnov · 2024-06-05T16:47:03Z

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 · 2024-06-05T17:45:10Z

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

✔️ ansible-galaxy-importer SUCCESS in 3m 23s
✔️ build-ansible-collection SUCCESS in 8m 26s

softwarefactory-project-zuul · 2024-06-06T13:48:14Z

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

✔️ ansible-galaxy-importer SUCCESS in 5m 23s
✔️ build-ansible-collection SUCCESS in 7m 56s

patchback · 2024-06-06T13:48:19Z

Backport to stable-3: 💚 backport PR created

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

Backported as #743

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

@tpo

Doc: add example of using kubectl connection plugin 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 Docs Pull Request 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 Reviewed-by: Bikouo Aubin Reviewed-by: Sandra McCann <[email protected]> Reviewed-by: Mike Graves <[email protected]> Reviewed-by: Yuriy Novostavskiy Reviewed-by: purdzan (cherry picked from commit fb80d97)

patchback · 2024-06-06T13:48:25Z

Backport to stable-5: 💚 backport PR created

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

Backported as #744

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

@tpo

Doc: add example of using kubectl connection plugin 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 Docs Pull Request 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 Reviewed-by: Bikouo Aubin Reviewed-by: Sandra McCann <[email protected]> Reviewed-by: Mike Graves <[email protected]> Reviewed-by: Yuriy Novostavskiy Reviewed-by: purdzan (cherry picked from commit fb80d97)

yurnov · 2024-06-06T14:06:16Z

Thanks @gravesm!

@tpo

[PR #741/fb80d973 backport][stable-3] Doc: add example of using kubectl connection plugin This is a backport of PR #741 as merged into main (fb80d97). 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 Docs Pull Request 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 Reviewed-by: Yuriy Novostavskiy Reviewed-by: Mike Graves <[email protected]>

@tpo

[PR #741/fb80d973 backport][stable-5] Doc: add example of using kubectl connection plugin This is a backport of PR #741 as merged into main (fb80d97). 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 Docs Pull Request 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 Reviewed-by: Mike Graves <[email protected]>

Add example of using kubectl connection plugin

aa0a497

yurnov mentioned this pull request Jun 1, 2024

add an example to the kubectl plugin #288

Closed

yurnov added 2 commits June 1, 2024 15:01

changelog fragment created

7b43249

fix linter

7e85312

fix sanity/linter

27464df

three hyphens as the berrinign of playbook in the example lead to "unparsable-with-libyaml: expected a single document in the stream - but found another document" error in yamllint, so three hyphens is removed in examples

abikouo reviewed Jun 3, 2024

View reviewed changes

abikouo added backport-3 backport-5 labels Jun 3, 2024

small changes based on code review feedback

c703cad

fix linter

8997a31

comment intendation aligned

samccann reviewed Jun 3, 2024

View reviewed changes

gravesm reviewed Jun 3, 2024

View reviewed changes

plugins/connection/kubectl.py Show resolved Hide resolved

plugins/connection/kubectl.py Outdated Show resolved Hide resolved

plugins/connection/kubectl.py Outdated Show resolved Hide resolved

yurnov added 2 commits June 3, 2024 16:18

typo fixed

710a5ad

update doc fragment accorging to last commit

c1bcd3e

doc fragment (docs/kubernetes.core.kubectl_connection.rst) is generated by collection_prep_add_docs

fix wrong example and avoid extra collections

f6879a7

yurnov requested review from gravesm and abikouo June 4, 2024 09:38

purdzan reviewed Jun 5, 2024

View reviewed changes

docs/kubernetes.core.kubectl_connection.rst Outdated Show resolved Hide resolved

fix typo

dfbd254

yurnov added 2 commits June 5, 2024 12:53

fix issue with variable and linter

205b88d

add changed_when: false for avoild failed linter

03be82d

yurnov requested a review from purdzan June 5, 2024 15:11

add .ansible-lint-ignore to ignore no-changed-when in examples

c9bbb69

and back echo "Hello, World"

add trailing end of line to .ansible-lint-ignore

e768753

gravesm approved these changes Jun 6, 2024

View reviewed changes

gravesm added the mergeit label Jun 6, 2024

softwarefactory-project-zuul bot merged commit fb80d97 into ansible-collections:main Jun 6, 2024
44 checks passed

patchback bot mentioned this pull request Jun 6, 2024

[PR #741/fb80d973 backport][stable-3] Doc: add example of using kubectl connection plugin #743

Merged

patchback bot mentioned this pull request Jun 6, 2024

[PR #741/fb80d973 backport][stable-5] Doc: add example of using kubectl connection plugin #744

Merged

yurnov deleted the kubectl_example branch June 6, 2024 14:06

This was referenced Jun 10, 2024

Prepare release 5.0.0 #733

Merged

Prepare version 3.2.0 #746

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc: add example of using kubectl connection plugin #741

Doc: add example of using kubectl connection plugin #741

yurnov commented Jun 1, 2024

softwarefactory-project-zuul bot commented Jun 1, 2024

softwarefactory-project-zuul bot commented Jun 1, 2024

tpo commented Jun 2, 2024 •

edited

Loading

yurnov commented Jun 3, 2024 •

edited

Loading

abikouo left a comment

yurnov commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

samccann left a comment

gravesm commented Jun 3, 2024

samccann commented Jun 3, 2024

yurnov commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

purdzan left a comment

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

yurnov commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 6, 2024

patchback bot commented Jun 6, 2024 •

edited

Loading

patchback bot commented Jun 6, 2024 •

edited

Loading

yurnov commented Jun 6, 2024

Doc: add example of using kubectl connection plugin #741

Doc: add example of using kubectl connection plugin #741

Conversation

yurnov commented Jun 1, 2024

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

softwarefactory-project-zuul bot commented Jun 1, 2024

softwarefactory-project-zuul bot commented Jun 1, 2024

tpo commented Jun 2, 2024 • edited Loading

yurnov commented Jun 3, 2024 • edited Loading

abikouo left a comment

Choose a reason for hiding this comment

yurnov commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

samccann left a comment

Choose a reason for hiding this comment

gravesm commented Jun 3, 2024

samccann commented Jun 3, 2024

yurnov commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

softwarefactory-project-zuul bot commented Jun 3, 2024

purdzan left a comment

Choose a reason for hiding this comment

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

yurnov commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 5, 2024

softwarefactory-project-zuul bot commented Jun 6, 2024

patchback bot commented Jun 6, 2024 • edited Loading

Backport to stable-3: 💚 backport PR created

patchback bot commented Jun 6, 2024 • edited Loading

Backport to stable-5: 💚 backport PR created

yurnov commented Jun 6, 2024

tpo commented Jun 2, 2024 •

edited

Loading

yurnov commented Jun 3, 2024 •

edited

Loading

patchback bot commented Jun 6, 2024 •

edited

Loading

patchback bot commented Jun 6, 2024 •

edited

Loading