Merge branch 'main' into edit-setup-content-initial

.github/.linkspector.yml

@@ -2,3 +2,6 @@ dirs:
   - ./content/
 
 useGitIgnore: true
+
+ignorePatterns:
+  - pattern: '^http://localhost:.*$'

content/docs/known-issues.md

@@ -0,0 +1,47 @@
+# Known issues
+
+Workaround solutions are available for the following MKE 4.0.0-alpha.1.0 known
+issues:
+
+## [BOP-708] OIDC authenticaion fails after mkectl upgrade
+
+Due to an issue with client secret migration, OIDC authentication fails
+following an upgrade performed with mkectl.
+
+**Workaround:**
+
+1. Copy the MKE 4 config that prints at the end of migration.
+
+2. Update the ``authentication.oidc.clientSecret`` field to the secret field
+   from your identity provider.
+
+3. Apply the updated MKE 4 config.
+
+## [BOP-686] In MKE 3 upgrade, kubectl commands return ``No agent available``
+
+For a cluster with multiple controller nodes (manager/master nodes), [k0s
+requires the presence ofa load balancer for the controller
+node](https://docs.k0sproject.io/head/high-availability/ ). Without a load
+balancer, the controller nodes is unable to reach the kubelet on the worker
+nodes, and thus the user will be presented with ``No agent available`` errors.
+
+**Workaround:**
+
+1. If an external load balancer is not already in place, create one that
+   targets all controllers and that forwards the following ports:
+
+   - `443`, for controller
+   - `6443`, for Kubernetes API
+   - `8132`, for Konnectivity
+
+2. Use `k0sctl` to update the `k0s` config to set `externalAddress`:
+
+   ```
+   k0s:
+     config:
+       spec:
+         api:
+           externalAddress: <load balancer public ip address>
+           sans:
+           - <load balancer public ip address>
+   ```

content/docs/reference/backuprestore/backup-restore.md

@@ -0,0 +1,64 @@
+# Backup and Restore
+
+>MKE 4 backup is enabled by default.
+
+MKE 4 supports backup and restore of cluster data through the use of the
+[Velero](https://velero.io/) addon.
+
+## Configuration
+
+The `backup` section of the MKE4 configuration file renders as follows:
+
+```yaml
+backup:
+  enabled: true
+  storage_provider:
+    type: InCluster
+    in_cluster_options:
+      exposed: true
+      distributed: false
+```
+
+By default, MKE 4 supports backups that use the in-cluster storage
+provider, as indicated in the `type` option setting of `InCluster`. MKE 4
+in-cluster backups are implemented using the [MinIO
+addon](https://microk8s.io/docs/addon-minio).
+
+The `exposed` option setting of `true` indicates that the MinIO service is
+exposed through `NodePort`, which Velero requires to function correctly. Core
+backup functionality should work, however, even if
+the service is not exposed.
+
+The `distributed` option configures MinIO storage to run in distributed mode.
+
+Refer to the following table for detail on all of the conifguration file
+`backup` fields:
+
+| Field                                                      | Description                                                                        | Valid values        |  Default  |
+|------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------|:---------:|
+| enabled                                                    | Indicates whether backup/restore functionality is enabled.                         | true, false         |    true   |
+| storage_provider.type                                      | Indicates whether the storage type in use is in-cluster or external.               | InCluster, External | InCluster |
+| storage_provider.in_cluster_options.exposed                | Indicates whether to expose InCluster (MinIO) storage through NodePort.            | true, false         |    true   |
+| storage_provider.in_cluster_options.distributed            | Indicates whether to run MinIO in distributed mode.                                | true, false         |   false   |
+| storage_provider.external_options.provider                 | Name of the external storage provider. AWS is currently the only available option. | aws                 |    aws    |
+| storage_provider.external_options.bucket                   | Name of the pre-created bucket to use for backup storage.                          | ""                  |     ""    |
+| storage_provider.external_options.region                   | Region in which the bucket exists.                                                 | ""                  |     ""    |
+| storage_provider.external_options.credentials_file_path    | Path to the credentials file.                                                      | ""                  |     ""    |
+| storage_provider.external_options.credentials_file_profile | Profile in the Credentials file to use.                                            | ""                  |     ""    |
+
+## Create backups and perform restores
+
+For information on how to create backups and perform restores for both storage
+provider types, refer to:
+
+- In-cluster storage provider: [in_cluster.md](./in_cluster.md)
+- External storage provider: [external.md](./external.md)
+
+## Existing Limitations
+
+- Scheduled backups, an MKE 3 feature that is planned for integration to MKE 4,
+  have not yet been implemented.
+
+- Backups must currently be restored in the same cluster in which the backup
+  was taken, and thus restoring a backup to a new set of nodes is not yet
+  supported for the in-cluster storage provider.

content/docs/reference/backuprestore/external.md

@@ -1,22 +1,24 @@
-# Backup and Restore Using External Storage Providers
+# Backup and restore using external storage providers
 
-It is possible to configure MKE to store backups and restores externally, for example in object storage provided by a public cloud provider. Currently only AWS S3 is supported as an external backup store.
+You can configure MKE 4 to store backups and restores externally, for example
+in object storage provided by a public cloud provider.
+
+>AWS S3 is currently the only supported external backup store
+>that MKE 4 supports.
 
 ## Configuration
 
-Prior to modifying the MKE configuration file, create an IAM credentials file. This file should look like below
-```
-[386383511305_docker-testing]
-aws_access_key_id=key
-aws_secret_access_key=secret
-aws_session_token=token
-```
+1. Copy the credentials information from the AWS console to create an IAM
+credentials file.
+
+   ![img.png](img.png)
 
-This can be easily copied from AWS console below:
+2. Edit the `storage_provider` section of the MKE configuration file to point
+to the file, including the profile name.
 
-![img.png](img.png)
+3. Create an S3 bucket and point the configuration to the bucket and region.
 
-Once the Credentials file is created, update the `storage_provider` section of the mke config file to point to the created creds file including the profile name. Additionally, you need to create an S3 bucket and point the configuration to the correct bucket and region. 
+Example configuration:
 
 ```yaml
   storage_provider:
@@ -29,27 +31,35 @@ Once the Credentials file is created, update the `storage_provider` section of t
       credentials_file_profile: "386383511305_docker-testing"
 ```
 
-## Usage
-
-Once AWS backup storage has been configured and the mke config file applied, check that the `BackupStorageLocation` CR exists and is ready. This may take a few minutes after `mkectl apply` is run.
+Once you have configured the AWS backup storage and the MKE configuration file
+has been applied, verify the existence of the `BackupStorageLocation` custom resource.
 
 ```shell
 kubectl get backupstoragelocation -n mke
 ```
 
-Output:
+> After you run `mkectl apply` the output may require a few minutes to display.
+
+Example output:
+
 ```shell
 NAME      PHASE       LAST VALIDATED   AGE   DEFAULT
 default   Available   20s              32s   true
 ```
 
-We can now create backups as usual and restore them. After creating a restore, the Kubernetes cluster state should resemble what it was when the backup was taken.
+## Create backups and perform restores
+
+With configuration complete, you can now create backups and perform restores
+from those backups. After you have run a restore operation from a backup, the
+Kubernetes cluster state should resemble what it was at the time you created
+that backup.
 
 ```shell
 mkectl backup create --name aws-backup
 ```
 
-Output:
+Example output:
+
 ```shell
 INFO[0000] Creating backup aws-backup...
 Backup request "aws-backup" submitted successfully.
@@ -63,23 +73,27 @@ INFO[0015] Waiting for backup to complete. Current phase: Completed
 INFO[0015] Backup aws-backup completed successfully
 ```
 
-List the backups:
+To list the backups, run the `mkectl backup list` command:
+
 ```shell
 mkectl backup list
 ```
 
-Output:
+Example output:
+
 ```shell
 NAME         STATUS      ERRORS   WARNINGS   CREATED                         EXPIRES   STORAGE LOCATION   SELECTOR
 aws-backup   Completed   0        0          2024-05-08 16:17:18 -0400 EDT   29d       default            <none>
 ```
 
-Create the restore:
+To perform a restore using an external backup, run:
+
 ```shell
 mkectl restore create --name aws-backup
 ```
 
-Output:
+Example output:
+
 ```shell
 INFO[0000] Waiting for restore aws-backup-20240508161811 to complete...
 INFO[0000] Waiting for restore to complete. Current phase: InProgress
@@ -94,17 +108,20 @@ INFO[0024] Waiting for restore to complete. Current phase: Completed
 INFO[0024] Restore aws-backup-20240508161811 completed successfully
 ```
 
-List the restores:
+To list the restores, run:
+
 ```shell
 mkectl restore list
 ```
 
-Output:
+Example output:
+
 ```shell
 NAME                        BACKUP       STATUS      STARTED                         COMPLETED                       ERRORS   WARNINGS   CREATED                         SELECTOR
 aws-backup-20240508161811   aws-backup   Completed   2024-05-08 16:18:11 -0400 EDT   2024-05-08 16:18:34 -0400 EDT   0        108        2024-05-08 16:18:11 -0400 EDT   <none>
 ```
 
-We can also see that both the backup and restore are created in our S3 bucket:
+From your AWS console, you can see that both the backup and restore are created
+in the S3 bucket:
 
 ![img_1.png](img_1.png)

content/docs/reference/backuprestore/in_cluster.md

@@ -1,8 +1,20 @@
-# Backup and Restore Using In Cluster Storage Provider
-By default, MKE will store backups and restores using the in cluster storage provider (MinIO). The below instructions assume you have created a cluster and applied a blueprint with the default MKE backup configuration.
+# Backup and restore using the in-cluster storage provider
 
-## Usage
-Backups can be created using `mkectl backup create --name <name>`.
+By default, MKE 4 stores backups and restores using the in-cluster storage
+provider, the [MinIO addon](https://microk8s.io/docs/addon-minio).
+
+>The offered instructions assume that you have created a cluster and
+applied a blueprint with the default MKE backup configuration.
+
+## Create an in-cluster backup
+
+To create an in-cluster backup, run:
+
+```shell
+mkectl backup create --name <name>
+```
+
+Example output:
 
 ```shell
 mkectl backup create --name test
@@ -17,17 +29,29 @@ INFO[0012] Waiting for backup to complete. Current phase: InProgress
 INFO[0015] Waiting for backup to complete. Current phase: Completed
 ```
 
-The backup should now be present in the MinIO bucket. You can list the backups using `mkectl backup list`.
+The backup should be present in the MinIO bucket. To list the backups, run
+the `mkectl backup list` command:
+
+Example output:
 
 ```shell
 mkectl backup list
 NAME   STATUS      ERRORS   WARNINGS   CREATED                         EXPIRES   STORAGE LOCATION   SELECTOR
 test   Completed   0        0          2024-05-07 17:29:18 -0400 EDT   29d       default            <none>
 ```
 
-Optionally, detailed logs of a backup can be viewed via `mkectl backup logs --name test`
+Optionally, you can view detailed logs of a backup by running the `mkectl
+backup logs --name test` command.
+
+## Restore from an in-cluster backup
 
-To create a restore off the backup we created we can run `mkectl restore create --name test`
+To perform a restore using an in-cluster backup, run:
+
+```shell
+mkectl restore create --name test
+```
+
+Example output:
 
 ```shell
 mkectl restore create --name test
@@ -45,14 +69,21 @@ INFO[0027] Waiting for restore to complete. Current phase: Completed
 INFO[0027] Restore test-20240507173309 completed successfully
 ```
 
-We can list the restores using `mkectl restore list`
+To list the restores, run:
+
+```shell
+ mkectl restore list
+ ```
+
+Example output:
 
 ```shell
 mkectl restore list
 NAME                  BACKUP   STATUS      STARTED                         COMPLETED                       ERRORS   WARNINGS   CREATED                         SELECTOR
 test-20240507173309   test     Completed   2024-05-07 17:33:09 -0400 EDT   2024-05-07 17:33:34 -0400 EDT   0        121        2024-05-07 17:33:09 -0400 EDT   <none>
 ```
 
-We can optionally view detailed logs similar to the backup logs using `mkectl restore logs --name test-20240507173309`.
+Optionally, you can view detailed logs by running the
+`mkectl restore logs --name test-20240507173309` command.