From 4a255c9969644281aa69524c4092f5723c6f2ed9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Mudrini=C4=87?= Date: Sun, 5 May 2019 23:05:17 +0200 Subject: [PATCH] Document how to migrate to the new API and changes made in the API (#410) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marko Mudrinić --- docs/README.md | 1 + docs/api_migration.md | 179 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 docs/api_migration.md diff --git a/docs/README.md b/docs/README.md index ce868360f..ed14b2bdd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ * [OpenStack](quickstart-openstack.md) * [Frequently Asked Questions](frequently_asked_questions.md) * [Backwards Compatibility Policy](backwards_compatibility_policy.md) +* [Migrating to the KubeOneCluster API](api_migration.md) * [Upgrading Kubernetes Cluster Using KubeOne](upgrading_cluster.md) * [Project Structure](project_structure.md) * [Environment variables used by KubeOne](environment_variables.md) diff --git a/docs/api_migration.md b/docs/api_migration.md new file mode 100644 index 000000000..d5300d54c --- /dev/null +++ b/docs/api_migration.md @@ -0,0 +1,179 @@ +# Migrating to the KubeOneCluster API + +We implemented a new KubeOneCluster API in v0.6.0 that replaced the old configuration API. +As the new API introduces many breaking changes, you can **not** continue using old manifests +as of v0.6.0. To continue using KubeOne, you have to migrate old manifests to +new KubeOneCluster manifests. + +The new API brings many possibilities and follows the Kubernetes API conventions. It allows us +to improve the user experience and ensure we can provide the +[backwards compatibility policy](./backwards_compatibility_policy.md). + +To make migration to the new API easier, we implemented the `config migrate` command that migrates +old configuration manifests to KubeOneCluster manifests. + +This document shows how to use the `config migrate` command and lists changes made in the new API. + +:warning: **Note: Before you can use the `config migrate` command you need to make sure that your manifests +are updated for KubeOne versions v0.4.0 or newer. If not, please see +[the changelog](https://github.com/kubermatic/kubeone/blob/master/CHANGELOG.md) to see what's new and what +are required actions to migrate.** :warning: + +## Using the `config migrate` command + +The `config migrate` can automatically migrate your old manifests to new KubeOneCluster manifests. +The command takes path to the old configuration manifest and prints the converted manifest. +Once the manifest is migrated, it is validated against the new API to ensure that all fields are +correct and contain correct values. + +```bash +kubeone config migrate config.yaml +``` + +For a `config.yaml` manifest that looks like the following one: + +```yaml +name: demo +provider: + name: aws +hosts: + - public_address: 1.1.1.1 + private_address: 1.1.1.2 +proxy: + http_proxy: 1.1.2.1 + https_proxy: 1.1.2.2 + no_proxy: 1.1.2.3 +features: + pod_security_policy: + enable: true +``` + +The `config migrate` command will print manifest such as: + +```yaml +name: demo +hosts: +- publicAddress: 1.1.1.1 + privateAddress: 1.1.1.2 +proxy: + http: 1.1.2.1 + https: 1.1.2.2 + noProxy: 1.1.2.3 +features: + podSecurityPolicy: + enable: true +apiVersion: kubeone.io/v1alpha1 +kind: KubeOneCluster +cloudProvider: + name: aws +``` + +**Note: The `apiVersion` and `kind` fields are not placed at the top automatically. +If you prefer, you can move them to the top manually.** + +## The API Changelog + +The new API introduces many changes to ensure the API follows the Kubernetes API conventions +and that we can provide as best as possible user experience. + +The most important changes include: + +* The API is now versioned, +* All fields are renamed to use the camel case notation, +* Some fields are renamed or replaced with new ones, so it's easier to understand what each +field is doing. + +### `apiVersion` and `kind` fields + +The `apiVersion` and `kind` fields must be added to the manifest. The `apiVersion` tells KubeOne +what API version you are using. When we change the API in a backwards incompatible way, we introduce +a new API version along with an automatic migration path. That ensures you can continue using the +old API as long as it's supported. To learn more for how long the old API versions are supported, +see the [backwards compatibility policy](./backwards_compatibility_policy.md). + +```yaml +apiVersion: kubeone.io/v1alpha1 +kind: KubeOneCluster +``` + +### Changes at the root level + +The following changes are introduced at the root level: + +* `apiserver` is replaced with the **`apiEndpoint`** structure, +* `provider` is renamed to **`cloudProvider`**, +* `network` is renamed to **`clusterNetwork`**, +* `machine_controller` is renamed to **`machineController`**. + +### `apiEndpoint` structure + +The `apiserver` structure is replaced with the **`apiEndpoint`** structure which contains the following fields: + +* **`host`** - address or hostname of the API endpoint (by default load balancer IP address or DNS), +* **`port`** - port used to access the Kubernetes API (by default `6443`). + +### `hosts` structure + +All fields in the `hosts` structure are renamed to use the camel case notation: + +* `public_address` -> **`publicAddress`** +* `private_address` -> **`privateAddress`** +* `ssh_port` -> **`sshPort`** +* `ssh_username` -> **`sshUsername`** +* `ssh_private_key_file` -> **`sshPrivateKeyFile`** +* `ssh_agent_socket` -> **`sshAgentSocket`** + +### `cloudProvider` structure + +The `provider` structure is renamed to **`cloudProvider`** and the `cloud_config` field is +renamed to `cloudConfig` (camel case notation). + +### `clusterNetwork` structure + +The `network` structure is renamed to `clusterNetwork`. All fields are renamed to use the camel case +notation and a new field is added: + +* `pod_subnet` -> **`podSubnet`** +* `service_subnet` -> **`serviceSubnet`** +* `node_port_range` -> **`nodePortRange`** +* [NEW] **`serviceDomainName`** (by default `cluster.local`) + +### `proxy` structure + +Fields in the `proxy` structure are renamed: + +* `http_proxy` -> **`http`** +* `https_proxy` -> **`https`** +* `no_proxy` -> **`noProxy`** + +### `features` structure + +All fields in the `features` structure are renamed to use the camel case notation: + +* `pod_security_policy` -> **`podSecurityPolicy`** +* `dynamic_audit_log` -> **`dynamicAuditLog`** +* `metrics_server` -> **`metricsServer`** +* `openid_connect` -> **`openidConnect`** + +### `workers` structure + +The `config` field is renamed to **`providerSpec`**. + +### `credentials` structure + +We're now storing credentials for the `machine-controller` and the external CCM at the root level, +in the **`credentials`** structure, instead of in `machineController.Credentials`. + +## The library changelog + +The following changes can affect using KubeOne as a Go library: + +* Structures are renamed to use the camel case notation and some structures are changed or removed +(see above points for more details), +* `WorkerConfig.ProviderSpec.CloudProviderSpec` and `WorkerConfig.ProviderSpec.OperatingSystemSpec` +are taking `json.RawMessage` instead of `map[string]interface{}`, +* All fields in the `Features` structure are now pointers. All fields for enabling the feature are +called `Enable` and are type of `bool` (previous pointer on `bool`), +* `MachineController` field is now a pointer of `MachineControllerConfig` +(previous `non-pointer MachineControllerConfig`), +* `MachineController.Deploy` is now `bool` instead of pointer on `bool`.