Skip to content
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

[DOC] Edit setup content initial #16

Merged
merged 17 commits into from
Jun 11, 2024
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
3c981e4
Initial edits to Setup content.
KoryKessel-Mirantis May 28, 2024
c9b2db0
Addition of k0s example and upgrade content edits.
KoryKessel-Mirantis May 29, 2024
f5e1bcc
Fix bad links in Installation and Terraform scenario.
KoryKessel-Mirantis May 29, 2024
8012fb3
Fix url for "System requirements for cluster nodes" heading by changi…
KoryKessel-Mirantis May 29, 2024
22f09bd
Add md filename to the "System requirements for cluster nodes" link i…
KoryKessel-Mirantis May 29, 2024
c6c2e3a
Edit in response to suggested edit to "Using the cluster" content.
KoryKessel-Mirantis May 30, 2024
19db78f
Edits based on SME reviewer comments.
KoryKessel-Mirantis Jun 6, 2024
ccba35c
Remove Known issues topic from PR.
KoryKessel-Mirantis Jun 7, 2024
77cfadf
Edits made in reference to comments form RyanZ and SakshiS.
KoryKessel-Mirantis Jun 7, 2024
5c35835
Edits in response to comments from SSharma and NNiesen, link fixes.
KoryKessel-Mirantis Jun 10, 2024
a94a19d
Fix to link in terraform-scenario, caused by filename change in previ…
KoryKessel-Mirantis Jun 10, 2024
88bc9a9
Insertion of mkectl download links
KoryKessel-Mirantis Jun 10, 2024
8e7e2a5
Added word 'image' to the mkectl download link text.
KoryKessel-Mirantis Jun 10, 2024
30f5b7a
Apply suggestions from code review
ry4nz Jun 10, 2024
4e0849d
Edits in response to review by Magda Dziadosz.
KoryKessel-Mirantis Jun 11, 2024
5c37935
Part 2: Edits in response to review by Magda Dziadosz.
KoryKessel-Mirantis Jun 11, 2024
7e89154
Final cleanup of markdown elements before merge.
KoryKessel-Mirantis Jun 11, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 0 additions & 85 deletions content/docs/setup/README.md

This file was deleted.

148 changes: 0 additions & 148 deletions content/docs/setup/getting-started/README.md

This file was deleted.

41 changes: 41 additions & 0 deletions content/docs/setup/getting-started/Using-the-cluster.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Using the cluster

You can use `kubectl` with the `mke` context to interact with the cluster,
though it is necessary to specify the configuration. `mkectl` outputs the
kubeconfig of the cluster to `~/mke/.mke.kubeconfig`.

You can apply ``.mke.kubeconfig`` using any one of the following methods:

- Set the KUBECONFIG env var to point to `~/.mke/mke.kubeconfig`

```shell
export KUBECONFIG=~/.mke/<cluster name>.kubeconfig
```

- Append the contents to the default kubeconfig:

```shell
cat ~/.mke/mke.kubeconfig >> ~/.kube/config
```

- Specify the config as a command argument:

```shell
kubectl --kubeconfig ~/.mke/mke.kubeconfig
```

Example output:

```text
$ kubectl --context mke get nodes
nwneisen marked this conversation as resolved.
Show resolved Hide resolved
NAME STATUS ROLES AGE VERSION
node1 Ready <none> 2d v1.29.3+k0s
node2 Ready control-plane 2d v1.29.3+k0s
```

To modify the cluster configuration, edit the YAML configuration file and
rerun the `apply` command.

```shell
mkectl apply -f mke.yaml
```
121 changes: 121 additions & 0 deletions content/docs/setup/getting-started/create-a-cluster.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Create a cluster

## Dependencies

A number of tools must be installed on your system before you can install MKE
4:
MagdaDziadosz marked this conversation as resolved.
Show resolved Hide resolved

- mkectl
- k0sctl
- kubectl

Refer to [Install the MKE 4 CLI](install-mke4-cli.md) for detailed information.

## Initialization

MKE 4 installation is performed through the use of a single YAML file,
detailing the desired cluster configuration. To generate this YAML file, run
the `mkectl init` command:

```shell
mkectl init > mke.yaml
```

In the configuration file, edit the `hosts` section to match your roster
of nodes.

> Configure the cluster nodes in advance, in accordance with the
[system
requirements](prerequisites.md#system-requirements-for-cluster-nodes).
>
> Node provisioning is managed by the cluster administrators. You can, for
instance, use Terraform to create the nodes in a
cloud provider. [Example Terraform
configuration](k0s-in-aws/terraform-scenario.md).

You must provide SSH information for each cluster node, as well as the role of
the node:

<dl>
<dt>controller+worker</dt>
<dd>A manager node that runs both control plane and data plane components.</dd>
<dt>worker</dt>
<dd>A worker node that runs the data plane components.</dd>
<dt>single</dt>
<dd>A special role, for use when the cluster consists of a single node.</dd>
</dl>
MagdaDziadosz marked this conversation as resolved.
Show resolved Hide resolved

<details>
<summary>Example: A ready-to-deploy MKE 4 config file</summary>

```yaml
hosts:
- ssh:
address: 1.1.1.1 # external IP of the first node
keyPath: /path/to/ssh/key.pem
port: 22
user: username
role: controller+worker
- ssh:
address: 2.2.2.2 # external IP of the second node
keyPath: /path/to/ssh/key.pem
port: 22
user: username
role: worker
hardening:
enabled: true
authentication:
enabled: true
saml:
enabled: false
oidc:
enabled: false
ldap:
enabled: false
backup:
enabled: true
storage_provider:
type: InCluster
in_cluster_options:
exposed: true
tracking:
enabled: true
trust:
enabled: true
logging:
enabled: true
audit:
enabled: true
license:
refresh: true
apiServer:
sans: ["mydomain.com"]
ingressController:
enabled: false
monitoring:
enableGrafana: true
enableOpscare: false
```

</details>

## Installation

To perform the installation, run the `apply` command with the generated YAML
configuration file:

```shell
mkectl apply -f mke.yaml
```

## Known limitations

- `mkectl apply` configures `mke` context in the default kubeconfig file that
is located at `~/.kube/config`. If the default kubeconfig is changed,
and the `mke` context becomes invalid or unavailable, `mkectl` will be unable
to manage the cluster until the kubeconfig is restored.
- You must not attempt to create a new cluster until you have first deleted the
existing cluster. If you do make such an attempt, even through the use of a
different config file, you will permanently lose access to the first cluster
through `mkectl`. For information on how to delete a cluster, refer to
[Uninstallation](uninstallation.md).
Loading