📖 clusterctl: initial set of documentation #1994

fabriziopandini · 2020-01-06T14:07:56Z

What this PR does / why we need it:
This PR creates the first set of documents for clusterctl:

intro
clusterctl init deep dive
configuring clusterctl
clusterctl providers contract

Being clusterctl a work in progress, also those pages should be considered WIP. At the same time, it is important to start sharing current assumptions and collect feedbacks

Which issue(s) this PR fixes
Fixes: #1490
Rif #1729

/assign @vincepri
/cc @akutz @yastij

fabriziopandini · 2020-01-15T18:24:24Z

@vincepri @vincepri
given that people are starting to play with the new clusterctl I made another iteration on this docs .with the goal to get some documentation out, even if the collocation in the book is not the final/some further iterations will be required when clusterctl feature set gets completed

docs/book/src/clusterctl/configuring-clusterctl.md

docs/book/src/clusterctl/intro.md

fabriziopandini · 2020-01-16T11:26:21Z

@ncdc many thanks for the feedback, really appreciated!
Everything must me addressed now

vuil · 2020-01-16T18:12:44Z

docs/book/src/clusterctl/contract.md

+
+The `clusterctl config cluster` command allows user to set a small set of common variables via CLI flags or command arguments.
+
+Templates writers should use the common variables to ensure consistency across providers and a simpler user experience


(less of a comment of the documentation itself but possibly something address in the future)

The absence of some these variables can lead to surprises in the UX. Say, if a template is opinionated about the number of control plane nodes it should create (e.g. a 'dev' template that hard codes that number to 1 to minimize resource usage), a user attempting to use said template while specifying

... --controlplane-machine-count 3 --worker-machine-count 5

would see only part of his intent satisfied in an otherwise fully functional configuration without warning

This is correct.
The authors of templates should provide documentation, and in case the template is opinionated, also the underlying assumptions (e.g. 1 worker to minimize resources) should be documented.

However, if this became a problem, we should always change this into a minimal set of required variables, but TBH, I fear this is too much restrictive ATM

vincepri

First pass, thanks for putting this together!

Regarding the structure I took inspiration / copied what kubectl has todayhttps://kubernetes.io/docs/reference/kubectl/overview which most users will be already familiar with.

docs/book/src/SUMMARY.md

vincepri · 2020-01-16T19:00:18Z

docs/book/src/SUMMARY.md

+    - [init](./clusterctl/init.md)
+    - [move](./clusterctl/move.md)
+    - [upgrade](./clusterctl/upgrade.md)
+    - [config cluster](clusterctl/config-cluster.md)
+    - [adopt](clusterctl/adopt.md)
+    - [delete](clusterctl/delete.md)


Let's put these underclusterctl Commands

I assume this should be a new subtree in the summary (done)

docs/book/src/SUMMARY.md

docs/book/src/clusterctl/contract.md

docs/book/src/clusterctl/configuring-clusterctl.md

docs/book/src/clusterctl/dev.md

docs/book/src/clusterctl/intro.md

vincepri · 2020-01-16T19:10:24Z

docs/book/src/clusterctl/intro.md

+
+See the [kind documentation](https://minikube.sigs.k8s.io/) for more details.
+{{#/tab }}
+{{#tab kind for docker provider}}


I'd honestly keep everything about CAPD separately, although I want to hear from other folks first

docs/book/src/clusterctl/configuring-clusterctl.md

docs/book/src/clusterctl/init.md

docs/book/src/clusterctl/intro.md

docs/book/src/clusterctl/contract.md

fabriziopandini · 2020-01-17T09:12:43Z

@ncdc, @vincepri @vuil comments should be addressed, thanks for feedback!

I have also added a new commit, with the dev documentation (mirrors the sam approach used for the Tilt doc)

ncdc

Just a couple minor things. LGTM!

docs/book/src/clusterctl/dev.md

vincepri · 2020-01-17T15:16:40Z

Doing another pass

docs/book/src/SUMMARY.md

vincepri · 2020-01-17T15:18:11Z

docs/book/src/SUMMARY.md

+        - [init](./clusterctl/init.md)
+        - [config cluster](clusterctl/config-cluster.md)
+        - [move](./clusterctl/move.md)
+        - [adopt](clusterctl/adopt.md)
+        - [upgrade](./clusterctl/upgrade.md)
+        - [delete](clusterctl/delete.md)


Prefix these files with command-? Such as ./clusterctl/command-init.md?

I moved all the command files into a command folder, is it ok for you?

docs/book/src/SUMMARY.md

docs/book/src/clusterctl/contract.md

vincepri · 2020-01-17T15:33:42Z

docs/book/src/clusterctl/contract.md

+The `clusterctl` command can ship with embedded metadata for pre-defined providers.
+If, as a provider implementer, you are interested to this feature, please send a PR to the Cluster API repository.


This seems the same as line 24-25

24-25 talks about the embedded list of providers
here it is talking about the embedded metadata

docs/book/src/clusterctl/contract.md

docs/book/src/clusterctl/intro.md

vincepri

/approve
/assign @ncdc

for final lgtm

k8s-ci-robot · 2020-01-17T17:32:57Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: fabriziopandini, vincepri

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [vincepri]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ncdc

These are my last review comments 😄. Please fix and then let's merge. We can open new PRs to fix more if needed.

docs/book/src/clusterctl/configuration.md

docs/book/src/clusterctl/overview.md

fabriziopandini · 2020-01-17T20:59:24Z

@ncdc comments addressed + squashed commits

ncdc · 2020-01-17T20:59:38Z

/lgtm

k8s-ci-robot assigned vincepri Jan 6, 2020

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 6, 2020

k8s-ci-robot requested review from akutz and yastij January 6, 2020 14:07

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jan 6, 2020

fabriziopandini mentioned this pull request Jan 13, 2020

Error message is hard to decipher #2055

Closed

fabriziopandini force-pushed the clusterctl-update-book branch from 8dac15d to 78e9694 Compare January 15, 2020 18:20

fabriziopandini changed the title ~~[WIP] 📖clusterctl: initial set of documentation~~ 📖clusterctl: initial set of documentation Jan 15, 2020

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 15, 2020

fabriziopandini changed the title ~~📖clusterctl: initial set of documentation~~ 📖 clusterctl: initial set of documentation Jan 15, 2020

ncdc reviewed Jan 15, 2020

View reviewed changes

vuil reviewed Jan 16, 2020

View reviewed changes

vincepri reviewed Jan 16, 2020

View reviewed changes

ncdc reviewed Jan 16, 2020

View reviewed changes

ncdc added this to the v0.3.0 milestone Jan 16, 2020

vuil reviewed Jan 17, 2020

View reviewed changes

docs/book/src/clusterctl/contract.md Outdated Show resolved Hide resolved

ncdc reviewed Jan 17, 2020

View reviewed changes

docs/book/src/clusterctl/dev.md Outdated Show resolved Hide resolved

docs/book/src/clusterctl/dev.md Outdated Show resolved Hide resolved

docs/book/src/clusterctl/dev.md Outdated Show resolved Hide resolved

vincepri reviewed Jan 17, 2020

View reviewed changes

vincepri approved these changes Jan 17, 2020

View reviewed changes

k8s-ci-robot assigned ncdc Jan 17, 2020

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 17, 2020

ncdc reviewed Jan 17, 2020

View reviewed changes

docs/book/src/clusterctl/configuration.md Outdated Show resolved Hide resolved

docs/book/src/clusterctl/configuration.md Outdated Show resolved Hide resolved

docs/book/src/clusterctl/overview.md Outdated Show resolved Hide resolved

first iteration on clusterctl docs

eea1679

fabriziopandini force-pushed the clusterctl-update-book branch from 506026c to eea1679 Compare January 17, 2020 20:58

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jan 17, 2020

k8s-ci-robot merged commit 9df2ec7 into kubernetes-sigs:master Jan 17, 2020

fabriziopandini deleted the clusterctl-update-book branch January 21, 2020 12:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 clusterctl: initial set of documentation #1994

📖 clusterctl: initial set of documentation #1994

fabriziopandini commented Jan 6, 2020 •

edited

Loading

fabriziopandini commented Jan 15, 2020

fabriziopandini commented Jan 16, 2020

vuil Jan 16, 2020 •

edited

Loading

fabriziopandini Jan 17, 2020

vincepri left a comment

vincepri Jan 16, 2020

fabriziopandini Jan 17, 2020 •

edited

Loading

vincepri Jan 16, 2020

fabriziopandini commented Jan 17, 2020

ncdc left a comment

vincepri commented Jan 17, 2020

vincepri Jan 17, 2020

fabriziopandini Jan 17, 2020

vincepri Jan 17, 2020

fabriziopandini Jan 17, 2020

vincepri left a comment

k8s-ci-robot commented Jan 17, 2020

ncdc left a comment

fabriziopandini commented Jan 17, 2020

ncdc commented Jan 17, 2020


		The `clusterctl config cluster` command allows user to set a small set of common variables via CLI flags or command arguments.

		Templates writers should use the common variables to ensure consistency across providers and a simpler user experience

		The `clusterctl` command can ship with embedded metadata for pre-defined providers.
		If, as a provider implementer, you are interested to this feature, please send a PR to the Cluster API repository.

📖 clusterctl: initial set of documentation #1994

📖 clusterctl: initial set of documentation #1994

Conversation

fabriziopandini commented Jan 6, 2020 • edited Loading

fabriziopandini commented Jan 15, 2020

fabriziopandini commented Jan 16, 2020

vuil Jan 16, 2020 • edited Loading

Choose a reason for hiding this comment

fabriziopandini Jan 17, 2020

Choose a reason for hiding this comment

vincepri left a comment

Choose a reason for hiding this comment

vincepri Jan 16, 2020

Choose a reason for hiding this comment

fabriziopandini Jan 17, 2020 • edited Loading

Choose a reason for hiding this comment

vincepri Jan 16, 2020

Choose a reason for hiding this comment

fabriziopandini commented Jan 17, 2020

ncdc left a comment

Choose a reason for hiding this comment

vincepri commented Jan 17, 2020

vincepri Jan 17, 2020

Choose a reason for hiding this comment

fabriziopandini Jan 17, 2020

Choose a reason for hiding this comment

vincepri Jan 17, 2020

Choose a reason for hiding this comment

fabriziopandini Jan 17, 2020

Choose a reason for hiding this comment

vincepri left a comment

Choose a reason for hiding this comment

k8s-ci-robot commented Jan 17, 2020

ncdc left a comment

Choose a reason for hiding this comment

fabriziopandini commented Jan 17, 2020

ncdc commented Jan 17, 2020

fabriziopandini commented Jan 6, 2020 •

edited

Loading

vuil Jan 16, 2020 •

edited

Loading

fabriziopandini Jan 17, 2020 •

edited

Loading