-
Notifications
You must be signed in to change notification settings - Fork 1.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
📖clusterctl: more docs #2266
Merged
k8s-ci-robot
merged 3 commits into
kubernetes-sigs:master
from
fabriziopandini:clusterctl-more-docs
Feb 12, 2020
Merged
📖clusterctl: more docs #2266
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,19 @@ | ||
# clusterctl adopt | ||
|
||
## Pre-requisites | ||
The `clusterctl adopt` command is designed for allowing users to start using clusterctl on management clusters originally | ||
created by installing providers with `kubectl apply <components-yaml>` instead of `clusterctl init`. | ||
|
||
The adoption process must be repeated for each provider installed in the cluster, thus allowing clusterctl to re-create | ||
the providers inventory as described in the `clusterctl init` [documentation](init.md#additional-information). | ||
|
||
### Labels | ||
## Pre-requisites | ||
|
||
In order for `clusterctl adopt` to work, ensure the components are correctly | ||
labeled. Please see the [provider contract labels][provider-contract-labels] for reference. | ||
|
||
<!-- links --> | ||
[provider-contract-labels]: ../provider-contract.md#labels | ||
|
||
## Adopting a provider | ||
|
||
TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,98 @@ | ||
# clusterctl config cluster | ||
|
||
The `clusterctl config cluster` command returns a YAML template for creating a workload cluster. | ||
|
||
For example | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 > my-cluster.yaml | ||
``` | ||
|
||
Creates a YAML file named `my-cluster.yaml` with a predefined list of Cluster API objects; Cluster, Machines, | ||
Machine Deployments, etc. to be deployed in the current namespace (in case, use the `--target-namespace` flag to | ||
specify a different target namespace). | ||
|
||
Then, the file can be modified using your editor of choice; when ready, run the following command | ||
to apply the cluster manifest. | ||
|
||
``` | ||
kubectl apply -f my-cluster.yaml | ||
``` | ||
|
||
### Selecting the infrastructure provider to use | ||
|
||
The `clusterctl config cluster` command uses smart defaults in order to simplify the user experience; in the example above, | ||
it detects that there is only an `aws` infrastructure provider in the current management cluster and so it automatically | ||
selects a cluster template from the `aws` provider's repository. | ||
|
||
In case there is more than one infrastructure provider, the following syntax can be used to select which infrastructure | ||
provider to use for the workload cluster: | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--infrastructure:aws > my-cluster.yaml | ||
``` | ||
|
||
or | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--infrastructure:aws:v0.4.1 > my-cluster.yaml | ||
``` | ||
|
||
### Flavors | ||
|
||
The infrastructure provider authors can provide different type of cluster templates, or flavors; use the `--flavor` flag | ||
to specify which flavor to use; e.g. | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--flavor high-availabilty > my-cluster.yaml | ||
``` | ||
|
||
Please refer to the providers documentation for more info about available flavors. | ||
|
||
### Alternative source for cluster templates | ||
|
||
clusterctl uses the provider's repository as a primary source for cluster templates; the following alternative sources | ||
for cluster templates can be used as well: | ||
|
||
#### ConfigMaps | ||
|
||
Use the `--from-config-map` flag to read cluster templates stored in a Kubernetes ConfigMap; e.g. | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--from-config-map my-templates > my-cluster.yaml | ||
``` | ||
|
||
Also following flags are available `--from-config-map-namespace` (defaults to current namespace) and `--from-config-map-key` | ||
(defaults to `template`). | ||
|
||
#### GitHub or local file system folder | ||
|
||
Use the `--from` flag to read cluster templates stored in a GitHub repository or in a local file system folder; e.g. | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--from https://github.com/my-org/my-repository/blob/master/my-template.yaml > my-cluster.yaml | ||
``` | ||
|
||
or | ||
|
||
``` | ||
clusterctl config cluster my-cluster --kubernetes-version v1.16.3 \ | ||
--from ~/my-template.yaml > my-cluster.yaml | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 😄 #2265 |
||
``` | ||
|
||
### Variables | ||
|
||
If the selected cluster template expects some environment variables, user should ensure those variables are set in advance. | ||
|
||
e.g. if the `AWS_CREDENTIALS` variable is expected for a cluster template targeting the `aws` infrastructure, you | ||
should ensure the corresponding environment variable to be set before executing `clusterctl config cluster`. | ||
|
||
Please refer to the providers documentation for more info about the required variables or use the | ||
`clusterctl config cluster --list-variables` flag to get a list of variables names required by a cluster template. | ||
|
||
The [clusterctl configuration](configuration.md) file can be used as alternative to environment variables. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,73 @@ | ||
# clusterctl | ||
# clusterctl upgrade | ||
|
||
The `clusterctl upgrade` command can be used to upgrade the version of the Cluster API providers (CRDs, controllers) | ||
installed into a management cluster. | ||
|
||
## Background info: management groups | ||
|
||
The upgrade procedure is designed to ensure all the providers in a *management group* use the same | ||
API Version of Cluster API (contract), e.g. the v1alpha 3 Cluster API contract. | ||
|
||
A management group is a group of providers composed by a CoreProvider and a set of Bootstrap/ControlPlane/Infrastructure | ||
providers watching objects in the same namespace. | ||
|
||
Usually, in a management cluster there is only a management group, but in case of [n-core multi tenancy](init.md#multi-tenancy) | ||
there can be more than one. | ||
|
||
# upgrade plan | ||
|
||
The `clusterctl upgrade plan` command can be used to identify possible targets for upgrades. | ||
|
||
|
||
```shell | ||
clusterctl upgrade plan | ||
``` | ||
|
||
Produces an output similar to this: | ||
|
||
```shell | ||
Checking new release availability... | ||
|
||
Management group: capi-system/cluster-api, latest release available for the v1alpha3 API Version of Cluster API (contract): | ||
|
||
NAME NAMESPACE TYPE CURRENT VERSION TARGET VERSION | ||
kubeadm-bootstrap capi-kubeadm-bootstrap-system BootstrapProvider v0.3.0 v0.3.1 | ||
cluster-api capi-system CoreProvider v0.3.0 v0.3.1 | ||
docker capd-system InfrastructureProvider v0.3.0 v0.3.1 | ||
|
||
|
||
You can now apply the upgrade by executing the following command: | ||
|
||
clusterctl upgrade apply --management-group capi-system/cluster-api --contract v1alpha3 | ||
``` | ||
|
||
The output contains the latest release available for each management group in the cluster/for each API Version of Cluster API (contract) | ||
available at the moment. | ||
|
||
# upgrade apply | ||
|
||
After choosing the desired option for the upgrade, you can run the provided command. | ||
|
||
```shell | ||
clusterctl upgrade apply --management-group capi-system/cluster-api --cluster-api-version v1alpha3 | ||
``` | ||
|
||
The upgrade process is composed by two steps: | ||
|
||
* Delete the current version of the provider components, while preserving the namespace where the provider components | ||
are hosted and the provider's CRDs. | ||
* Install the new version of the provider components. | ||
|
||
Please note that clusterctl does not upgrade Cluster API objects (Clusters, MachineDeployments, Machine etc.); upgrading | ||
such objects are the responsibility of the provider's controllers. | ||
|
||
<aside class="note warning"> | ||
|
||
<h1>Warning!</h1> | ||
|
||
The current implementation of the upgrade process does not preserve controllers flags that are not set through the | ||
components YAML/at the installation time. | ||
|
||
User is required to re-apply flag values after the upgrade completes. | ||
|
||
</aside> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
--from-config-map
is currently not a supported flag. Is there another PR adding this functionality in?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
😄 #2265
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should document the other flags
--from-config-map-key
and--from-config-map-namespace
. I was testing this out and was about to open issues for those scenarios but then I saw the other flags in the help output. 😄