From bb596039de59ab6925f5f6a25d81fd780096c194 Mon Sep 17 00:00:00 2001 From: Evan Johnson Date: Fri, 19 Apr 2024 12:18:19 -0400 Subject: [PATCH] update docs to reflect installing CAPL from release artifacts --- Makefile | 2 +- docs/src/developers/development.md | 19 +++++++-------- docs/src/developers/releasing.md | 21 ++++------------ docs/src/topics/backups.md | 5 ++-- docs/src/topics/etcd.md | 2 +- docs/src/topics/flavors/cluster-autoscaler.md | 3 ++- .../topics/flavors/clusterclass-kubeadm.md | 4 +++- docs/src/topics/flavors/default.md | 3 ++- docs/src/topics/flavors/dual-stack.md | 3 ++- .../src/topics/flavors/etcd-backup-restore.md | 13 ++++++++++ docs/src/topics/flavors/etcd-disk.md | 5 ++-- docs/src/topics/flavors/k3s.md | 6 ++--- docs/src/topics/flavors/rke2.md | 6 ++--- docs/src/topics/getting-started.md | 24 ++++++++----------- docs/src/topics/health-checking.md | 2 +- 15 files changed, 58 insertions(+), 60 deletions(-) diff --git a/Makefile b/Makefile index 0d339dcd4..7e3982f5c 100644 --- a/Makefile +++ b/Makefile @@ -239,7 +239,7 @@ release-manifests: $(KUSTOMIZE) $(RELEASE_DIR) .PHONY: local-release local-release: - RELEASE_DIR=infrastructure-linode/0.0.0 $(MAKE) release + RELEASE_DIR=infrastructure-linode/v0.0.0 $(MAKE) release $(MAKE) clean-release-git ## -------------------------------------- diff --git a/docs/src/developers/development.md b/docs/src/developers/development.md index 8845b636e..861451d74 100644 --- a/docs/src/developers/development.md +++ b/docs/src/developers/development.md @@ -17,7 +17,7 @@ - [Customizing the cluster deployment](#customizing-the-cluster-deployment) - [Creating the workload cluster](#creating-the-workload-cluster) - [Using the default flavor](#using-the-default-flavor) - - [Using ClusterClass (alpha)](#using-clusterclass) + - [Using ClusterClass (alpha)](#using-clusterclass-alpha) - [Cleaning up the workload cluster](#cleaning-up-the-workload-cluster) - [Automated Testing](#automated-testing) - [E2E Testing](#e2e-testing) @@ -142,7 +142,7 @@ kind delete cluster --name tilt After your kind management cluster is up and running with Tilt, you should be ready to deploy your first cluster. -#### Generating the cluster templates +#### Generating local cluster templates For local development, templates should be generated via: @@ -150,10 +150,10 @@ For local development, templates should be generated via: make local-release ``` -This creates `infrastructure-linode/0.0.0/` with all the cluster templates: +This creates `infrastructure-linode/v0.0.0/` with all the cluster templates: ```sh -infrastructure-linode/0.0.0 +infrastructure-linode/v0.0.0 ├── cluster-template-clusterclass-kubeadm.yaml ├── cluster-template-etcd-backup-restore.yaml ├── cluster-template-k3s.yaml @@ -169,8 +169,8 @@ This can then be used with `clusterctl` by adding the following to `~/.clusterct ``` providers: - - name: linode - url: ${HOME}/cluster-api-provider-linode/infrastructure-linode/0.0.0/infrastructure-components.yaml + - name: akamai-linode + url: ${HOME}/cluster-api-provider-linode/infrastructure-linode/v0.0.0/infrastructure-components.yaml type: InfrastructureProvider ``` @@ -181,7 +181,6 @@ Here is a list of required configuration parameters: ```sh ## Cluster settings export CLUSTER_NAME=capl-cluster -export KUBERNETES_VERSION=v1.29.1 ## Linode settings export LINODE_REGION=us-ord @@ -195,7 +194,7 @@ export LINODE_MACHINE_TYPE=g6-standard-2 You can also use `clusterctl generate` to see which variables need to be set: ``` -clusterctl generate cluster $CLUSTER_NAME --infrastructure linode:0.0.0 [--flavor ] --list-variables +clusterctl generate cluster $CLUSTER_NAME --infrastructure akamai-linode:v0.0.0 [--flavor ] --list-variables ``` ~~~ @@ -210,7 +209,7 @@ you can deploy a workload cluster with the default flavor: ```sh clusterctl generate cluster $CLUSTER_NAME \ --kubernetes-version v1.29.1 \ - --infrastructure linode:0.0.0 \ + --infrastructure akamai-akamai-linode:v0.0.0 \ | kubectl apply -f - ``` @@ -230,7 +229,7 @@ management cluster has the [ClusterTopology feature gate set](https://cluster-ap ```sh clusterctl generate cluster $CLUSTER_NAME \ --kubernetes-version v1.29.1 \ - --infrastructure linode:0.0.0 \ + --infrastructure akamai-linode:v0.0.0 \ --flavor clusterclass-kubeadm \ | kubectl apply -f - ``` diff --git a/docs/src/developers/releasing.md b/docs/src/developers/releasing.md index 56004319a..96a0bfa40 100644 --- a/docs/src/developers/releasing.md +++ b/docs/src/developers/releasing.md @@ -11,7 +11,7 @@ backported to the current and previous release lines. ## Versioning Scheme -CAPL follows the [semantic versionining](https://semver.org/#semantic-versioning-200) specification. +CAPL follows the [semantic versioning](https://semver.org/#semantic-versioning-200) specification. Example versions: @@ -25,26 +25,13 @@ Example versions: ### Update metadata.yaml (skip for patch releases) - Make sure [metadata.yaml](https://github.com/linode/cluster-api-provider-linode/blob/main/metadata.yaml) -is up to date and contains the new release with the correct Cluster API contract version. +is up-to-date and contains the new release with the correct Cluster API contract version. - If not, open a PR to add it. -### Create a release branch (skip for patch releases) - -- Create a release branch off of `main` named -`release-$(MAJOR_VERSION).$(MINOR_VERSION)` (e.g. release-0.1) - -### Create a tag for the release branch - -- After ensuring all desired changes for the release are in the release branch, -create a tag following semantic versioning (e.g. v0.1.1) -- Ensure the [release workflow](https://github.com/linode/cluster-api-provider-linode/actions/workflows/release.yml) -succeeds for the created tag to build and push the Docker image and generate -the [release artifacts](#expected-artifacts). - ### Release in GitHub - Create a [new release](https://github.com/linode/cluster-api-provider-linode/releases/new). - - Use the newly created tag + - Enter tag and select create tag on publish - Make sure to click "Generate Release Notes" - Review the generated Release Notes and make any necessary changes. - If the tag is a pre-release, make sure to check the "Set as a pre-release box" @@ -52,7 +39,7 @@ the [release artifacts](#expected-artifacts). ### Expected artifacts - A `infrastructure-components.yaml` file containing the resources needed to deploy to Kubernetes -- A `cluster-templates.yaml` file for each supported flavor +- A `cluster-templates-*.yaml` file for each supported flavor - A `metadata.yaml` file which maps release series to the Cluster API contract version ### Communication diff --git a/docs/src/topics/backups.md b/docs/src/topics/backups.md index fa5f5a4cc..0f41de5d4 100644 --- a/docs/src/topics/backups.md +++ b/docs/src/topics/backups.md @@ -12,7 +12,7 @@ To enable backups, use the addon flag during provisioning to select the etcd-bac ```sh clusterctl generate cluster $CLUSTER_NAME \ --kubernetes-version v1.29.1 \ - --infrastructure linode:0.0.0 \ + --infrastructure akamai-linode \ --flavor etcd-backup-restore \ | kubectl apply -f - ``` @@ -49,7 +49,7 @@ The bucket label must be unique within the region across all accounts. Otherwise ### Access Keys Creation -CAPL will also create `read_write` and `read_only` access keys for the bucket and store credentials in a secret in the same namespace where the `LinodeObjectStorageBucket` was created alongwith other details about the Linode OBJ Bucket: +CAPL will also create `read_write` and `read_only` access keys for the bucket and store credentials in a secret in the same namespace where the `LinodeObjectStorageBucket` was created along with other details about the Linode OBJ Bucket: ```yaml apiVersion: v1 @@ -62,6 +62,7 @@ metadata: kind: LinodeObjectStorageBucket name: controller: true + uid: data: bucket_name: bucket_region: diff --git a/docs/src/topics/etcd.md b/docs/src/topics/etcd.md index 98d3a3ba6..e69ac014a 100644 --- a/docs/src/topics/etcd.md +++ b/docs/src/topics/etcd.md @@ -39,7 +39,7 @@ export ETCDBR_IMAGE=docker.io/username/your-custom-image:version export SSE_KEY=cdQdZ3PrKgm5vmqxeqwQCuAWJ7pPVyHg clusterctl generate cluster $CLUSTER_NAME \ --kubernetes-version v1.29.1 \ - --infrastructure linode:0.0.0 \ + --infrastructure akamai-linode \ --flavor etcd-backup-restore \ | kubectl apply -f - ``` diff --git a/docs/src/topics/flavors/cluster-autoscaler.md b/docs/src/topics/flavors/cluster-autoscaler.md index 63ab643d2..ef7bfc39c 100644 --- a/docs/src/topics/flavors/cluster-autoscaler.md +++ b/docs/src/topics/flavors/cluster-autoscaler.md @@ -32,7 +32,8 @@ Autoscaler](https://www.github.com/kubernetes/autoscaler/tree/master/cluster-aut ```sh clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode \ --flavor cluster-autoscaler > test-cluster.yaml ``` diff --git a/docs/src/topics/flavors/clusterclass-kubeadm.md b/docs/src/topics/flavors/clusterclass-kubeadm.md index 72f63864d..37853c2bf 100644 --- a/docs/src/topics/flavors/clusterclass-kubeadm.md +++ b/docs/src/topics/flavors/clusterclass-kubeadm.md @@ -10,7 +10,8 @@ 1. Generate the ClusterClass and cluster manifests ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode \ --flavor clusterclass-kubeadm > test-cluster.yaml ``` 2. Apply cluster manifests @@ -21,6 +22,7 @@ 1. Generate cluster manifests ```bash clusterctl generate cluster test-cluster-2 \ + --kubernetes-version v1.29.1 \ --flavor clusterclass-kubeadm > test-cluster-2.yaml ``` ```yaml diff --git a/docs/src/topics/flavors/default.md b/docs/src/topics/flavors/default.md index d9278aec8..89680bdf5 100644 --- a/docs/src/topics/flavors/default.md +++ b/docs/src/topics/flavors/default.md @@ -9,7 +9,8 @@ 1. Generate cluster yaml ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 > test-cluster.yaml + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode > test-cluster.yaml ``` 2. Apply cluster yaml ```bash diff --git a/docs/src/topics/flavors/dual-stack.md b/docs/src/topics/flavors/dual-stack.md index 26e3d1306..1a5624480 100644 --- a/docs/src/topics/flavors/dual-stack.md +++ b/docs/src/topics/flavors/dual-stack.md @@ -9,7 +9,8 @@ 1. Generate cluster yaml ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode \ --flavor dual-stack > test-cluster.yaml ``` 2. Apply cluster yaml diff --git a/docs/src/topics/flavors/etcd-backup-restore.md b/docs/src/topics/flavors/etcd-backup-restore.md index a6d6962c4..ae097f978 100644 --- a/docs/src/topics/flavors/etcd-backup-restore.md +++ b/docs/src/topics/flavors/etcd-backup-restore.md @@ -7,6 +7,19 @@ ## Prerequisites [Quickstart](../getting-started.md) completed +## Usage +1. Generate cluster yaml + ```bash + clusterctl generate cluster test-cluster \ + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode \ + --flavor etcd-backup-restore > test-cluster.yaml + ``` +2. Apply cluster yaml + ```bash + kubectl apply -f test-cluster.yaml + ``` + ## Notes This flavor is identical to the default flavor with the addon etcd-backup-restore enabled diff --git a/docs/src/topics/flavors/etcd-disk.md b/docs/src/topics/flavors/etcd-disk.md index 7f60a93b2..f0036de50 100644 --- a/docs/src/topics/flavors/etcd-disk.md +++ b/docs/src/topics/flavors/etcd-disk.md @@ -8,7 +8,7 @@ the `quota-backend-bytes` to `8589934592` (8 GiB) per recommendation from ## Specification | Control Plane | CNI | Default OS | Installs ClusterClass | IPv4 | IPv6 | |---------------|--------|--------------|-----------------------|------|------| -| Kubeadm | Cilium | Ubuntu 22.04 | No | Yes | No | +| Kubeadm | Cilium | Ubuntu 22.04 | No | Yes | No | ## Prerequisites [Quickstart](../getting-started.md) completed @@ -17,7 +17,8 @@ the `quota-backend-bytes` to `8589934592` (8 GiB) per recommendation from 1. Generate cluster yaml ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1 \ + --infrastructure akamai-linode \ --flavor etcd-disk > test-cluster.yaml ``` 2. Apply cluster yaml diff --git a/docs/src/topics/flavors/k3s.md b/docs/src/topics/flavors/k3s.md index 944c34a4d..afcfa11db 100644 --- a/docs/src/topics/flavors/k3s.md +++ b/docs/src/topics/flavors/k3s.md @@ -6,9 +6,6 @@ ## Prerequisites * [Quickstart](../getting-started.md) completed * Select a [k3s kubernetes version](https://github.com/k3s-io/k3s/releases) to set for the kubernetes version - ```bash - export KUBERNETES_VERSION=v1.29.1+k3s2 - ``` * Installed [k3s bootstrap provider](https://github.com/k3s-io/cluster-api-k3s) into your management cluster * Add the following to `~/.cluster-api/clusterctl.yaml` for the k3s bootstrap/control plane providers ```yaml @@ -29,7 +26,8 @@ 1. Generate cluster yaml ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1+k3s2 \ + --infrastructure akamai-linode \ --flavor k3s > test-k3s-cluster.yaml ``` 2. Apply cluster yaml diff --git a/docs/src/topics/flavors/rke2.md b/docs/src/topics/flavors/rke2.md index 8a772689f..1312fdcf3 100644 --- a/docs/src/topics/flavors/rke2.md +++ b/docs/src/topics/flavors/rke2.md @@ -6,9 +6,6 @@ ## Prerequisites * [Quickstart](../getting-started.md) completed * Select an [rke2 kubernetes version](https://github.com/rancher/rke2/releases) to set for the kubernetes version - ```bash - export KUBERNETES_VERSION=v1.29.1+rke2r1 - ``` * Installed [rke2 bootstrap provider](https://github.com/rancher-sandbox/cluster-api-provider-rke2) into your management cluster ```shell clusterctl init --bootstrap rke2 --control-plane rke2 @@ -17,7 +14,8 @@ 1. Generate cluster yaml ```bash clusterctl generate cluster test-cluster \ - --infrastructure linode:0.0.0 \ + --kubernetes-version v1.29.1+rke2r1 \ + --infrastructure akamai-linode \ --flavor rke2 > test-rke2-cluster.yaml ``` 2. Apply cluster yaml diff --git a/docs/src/topics/getting-started.md b/docs/src/topics/getting-started.md index 387219f7c..08b9f3155 100644 --- a/docs/src/topics/getting-started.md +++ b/docs/src/topics/getting-started.md @@ -12,7 +12,8 @@ Make sure to create the token with at least the following read/write permissions - VPCs - IPs - Object Storage - +- clusterctl is [installed](https://cluster-api.sigs.k8s.io/user/quick-start#installation) +- Cluster API [management cluster](https://cluster-api.sigs.k8s.io/user/quick-start#install-andor-configure-a-kubernetes-cluster) is created ```admonish question title="" For more information please see the [Linode Guide](https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/#create-an-api-token). @@ -22,11 +23,6 @@ For more information please see the Once you have provisioned your PAT, save it in an environment variable along with other required settings: ```bash -# Cluster settings -export CLUSTER_NAME=capl-cluster -export KUBERNETES_VERSION=v1.29.1 - -# Linode settings export LINODE_REGION=us-ord export LINODE_TOKEN= export LINODE_CONTROL_PLANE_MACHINE_TYPE=g6-standard-2 @@ -37,19 +33,19 @@ For Regions and Images that do not yet support Akamai's cloud-init datasource CA to provision the node. If you are using a custom image ensure the [cloud_init](https://www.linode.com/docs/api/images/#image-create) flag is set correctly on it ``` -## Register linode locally as an infrastructure provider -1. Generate local release files - ```bash - make local-release - ``` -2. Add `linode` as an infrastructure provider in `~/.cluster-api/clusterctl.yaml` +## Register linode as an infrastructure provider +1. Add `linode` as an infrastructure provider in `~/.cluster-api/clusterctl.yaml` ```yaml providers: - - name: linode - url: ${PWD}/infrastructure-linode/0.0.0/infrastructure-components.yaml + - name: akamai-linode + url: https://github.com/linode/cluster-api-provider-linode/releases/latest/infrastructure-components.yaml type: InfrastructureProvider ``` +## Install CAPL on your management cluster +1. clusterctl init --infrastructure akamai-linode + + ## Deploying your first cluster Please refer to the [default flavor](../topics/flavors/default.md) section for creating your first Kubernetes cluster on Linode using Cluster API. diff --git a/docs/src/topics/health-checking.md b/docs/src/topics/health-checking.md index 9fcbe5810..dafb351ee 100644 --- a/docs/src/topics/health-checking.md +++ b/docs/src/topics/health-checking.md @@ -10,7 +10,7 @@ using the `self-healing` flavor is the quickest way to get started: ```sh clusterctl generate cluster $CLUSTER_NAME \ --kubernetes-version v1.29.1 \ - --infrastructure linode:0.0.0 \ + --infrastructure akamai-linode \ --flavor self-healing \ | kubectl apply -f - ```