[DOC] Architecture update

content/docs/concepts/architecture/architecture.md

@@ -0,0 +1,50 @@
+# MKE Architecture
+
+Mirantis Kubernetes Engine (MKE) 4 is an enterprise-grade, production-ready
+Kubernetes platform that is designed to be secure, scalable, and reliable.
+
+You can manage the entire MKE 4 cluster through the MKE configuration file.
+Refer to [Configuration and blueprints](configuration.md) for more information.
+
+## Components
+
+MKE 4 is built on top of k0s, a lightweight Kubernetes distribution.
+Refer to the [official k0s documentation](https://docs.k0sproject.io/v1.29.3+k0s.0/)
+for more information.
+
+<!-- ### Control plane -->
+
+<!-- [Discuss the control plane component and its function] -->
+
+### Container Network Interface
+
+By default, Calico is installed as the Container Network Interface (CNI) plugin, with the following configuration:
+
+- IPv4 only, with a fixed Pod CIDR of `10.244.0.0/16`.
+- The datastore mode set to `kdd`.
+- `kube-proxy` set to `iptables` mode.
+- A `vxlan` backend, which uses the default port of `4789` for traffic and default virtual network ID of `4096`.
+
+The MKE 4 Alpha.1 release has the following limitations:
+
+- The CNI plugin cannot be changed.
+- Calico cannot be reconfigured.
+- The Calico configuration is not migrated during an upgrade to MKE4 from MKE 3.
+
+<!-- ### Data Plane -->
+
+<!-- [Discuss the data plane components and their functions] -->
+
+<!-- ## High-Level Diagram -->
+
+<!-- [Include a high-level diagram illustrating the MKE architecture] -->
+
+<!-- ## Deployment considerations -->
+
+<!-- [Highlight any important considerations for deploying MKE] -->
+
+<!-- ## Conclusion [Wrap up the document with a conclusion or summary] -->
+
+<!-- ### Control plane -->
+
+<!-- [Discuss the control plane component and its function] -->

content/docs/concepts/architecture/configuration.md

@@ -1,57 +1,92 @@
-## MKE4 Configuration & Blueprints
-The MKE4 Configuration file contains an opinionated configuration on how to set up the MKE cluster. It lets the user define details about their cluster such as how many nodes there are in the cluster, how to access the nodes, and any specific MKE4 feature that you want to enable/disable. The simple MKE4 configuration file is translated into a more complex Blueprint that contains the granular details of how to set up the cluster.
+# Configuration and blueprints
 
+The Mirantis Kubernetes Engine (MKE) 4 configuration file contains an
+opinionated configuration on how to set up the MKE cluster.
 
-### Creating your Config
-A default MKE config can be generated by running `mkectl init > mke.yaml`. This will generate a default config that you can modify to deploy MKE on your cluster.
+With the MKE configuration file, you can:
 
-To apply your config to a set of pre-existing machines, modify the `hosts` section of the config.
+- Define the number of nodes in the cluster.
+- Define ways to access the nodes.
+- Enable or disable certain MKE components.
+- Configure MKE component features
 
-An example of a hosts section is shown below:
+Once set, the MKE configuration file is translated into a more complex
+blueprint that contains the granular details on how to set up the cluster.
 
-```yaml
-hosts:
-- ssh:
-    address: 18.224.23.158
-    keyPath: "/absolute/path/to/private/key.pem"
-    port: 22
-    user: root
-  role: controller+worker
-- ssh:
-    address: 18.224.23.158
-    keyPath: "/absolute/path/to/private/key.pem"
-    port: 22
-    user: ubuntu
-  role: worker
-- ssh:
-    address: 18.117.87.45
-    keyPath: "/absolute/path/to/private/key.pem"
-    port: 22
-    user: ubuntu
-  role: worker
-```
+## Create configuration
 
-For users migrating from MKE3, it is possible to pass some options to `mkectl` to migrate your settings directly from MKE3.
+1. Generate the default MKE configuration file by running:
 
-To pass in a downloaded MKE3 config file set the `--mke3-config` flag. This will convert the local MKE3 config into a valid MKE4 config.
+    ```commandline
+    mkectl init > mke.yaml
+    ```
 
-`mkectl init --mke3-config /path/to/mke3-config.toml`
+2. Modify the `hosts` section of the MKE configuration file, to apply the
+   configuration to a set of pre-existing machines that you have set up in
+   advance:
 
-Alternatively you can provide `mkectl` with the credentials to connect to an MKE3 Cluster, which will allow `mkectl` to retrieve the MKE3 config itself and then convert it to an MKE4 config.
+    ```yaml
+    hosts:
+    - ssh:
+        address: 18.224.23.158
+        keyPath: "/absolute/path/to/private/key.pem"
+        port: 22
+        user: root
+      role: controller+worker
+    - ssh:
+        address: 18.224.23.158
+        keyPath: "/absolute/path/to/private/key.pem"
+        port: 22
+        user: ubuntu
+      role: worker
+    - ssh:
+        address: 18.117.87.45
+        keyPath: "/absolute/path/to/private/key.pem"
+        port: 22
+        user: ubuntu
+      role: worker
+    ```
 
-`mkectl init --mke3-admin-username admin --mke3-admin-password password --mke3-hostname mke3.example.com`
+## Choose addons
 
-### Choosing Addons
-A core part of MKE4 is the ability to selectively install addons from from a set of curated and tested addons. `mkectl init` will enable a set of default addons that are considered core to MKE4. You can modify the generated config to enable/disable additional addons as you wish, as well as modify settings on each particular addon.
+A core component of MKE 4 is a default set of curated and tested addons that you
+can install by running `mkectl init` and subsequently applying the generated
+configuration file.
 
-### Blueprints
-MKE4 uses the blueprint operator under the hood. All MKE4 configs are translated into blueprints. A blueprint is a special type of file that is used to create a Kubernetes Custom Resource (CRD) also called a Blueprint. Thus the blueprint file must be valid Kubernetes YAML and contains many of the same fields as standard Kubernetes Objects.
+Using the MKE configuration file, you can enable and disable the MKE 4 addons,
+as well as modify their settings. In addition, you can use the
+`mkectl init` command with the `--blueprint` option to print the generated
+blueprint that reflects your current MKE 4 configuration.
 
-A blueprint is roughly composed of 3 sections.
-1. The section detailing the Kubernetes Provider and any specific settings for that provider. This section is mostly managed by `mkectl` independently of the user provided MKE config.
-2. The section detailing the infrastructure that will be used for the Kubernetes Cluster. This is essentially just the `hosts` section of the MKE config.
-3. The components section. This section is composed of the various addons specified in the MKE config. `mkectl` takes the user-friendly MKE config options and translates them into specific settings in either Helm or Manifest type addons that are deployed into the cluster.
+## Blueprints
 
-To see the detailed blueprint of a MKE config you can run `mkectl init --blueprint`. It is possible to modify the blueprint directly but any such modifications are considered advanced and not officially supported by MKE.
+All MKE 4 configuration files are translated into blueprints,
+a file type that is used to create Kubernetes Custom Resources (CRDs)
+that are also called blueprints. MKE 4 uses Blueprint Operator to manage blueprints and their assignments.
+
+Blueprint files must be in Kubernetes YAML format,
+and they must contain many of the same fields as a standard Kubernetes Object.
+
+A blueprint comprises three sections:
+
+<dl>
+  <dt><strong>Kubernetes Provider</strong></dt>
+  <dd>Details the settings for the provider. For the most part, the Kubernetes Provider section is is managed by <code>mkectl</code>, independently of the user's MKE configuration file. </dd>
+  <dt><strong>Infrastructure</strong></dt>
+  <dd>Provides details that are used for the Kubernetes cluster; the <code>hosts</code> section of the MKE configuration file.</dd>
+  <dt><strong>Components</strong></dt>
+  <dd>Composed of addons that are specified in the MKE configuration file. The <code>mkectl</code> command transforms the configuration options
+into specific settings for either Helm or Manifest type addons that are deployed into the cluster.</dd>
+</dl>
+
+To view a detailed blueprint of an MKE configuration, run the `mkectl init --blueprint` command.
+
+> It is possible to directly modify a blueprint, however, such modifications are
+> considered advanced and support by MKE 4 is not assured.
+
+<!-- Please see the Blueprint Operator [documentation](https://mirantiscontainers.github.io/boundless/) for more details on blueprints. - broken link -->
+
+<!-- Discuss with SME NNeisen moving "Create configuration" to "Getting Started" -->
+
+<!-- Discuss reduction of Blueprint section here, instead sending readers to blueprint documentation at https://mirantiscontainers.github.io/blueprint/ -->
 
-Please see the blueprint operator [documentation](https://mirantiscontainers.github.io/boundless/) for more details on blueprints.

content/docs/concepts/architecture/migrate-configuration.md

@@ -0,0 +1,13 @@
+# Migrate configuration
+
+In migrating to MKE 4 from MKE 3, you can directly transfer settings by passing
+several options to `mkectl`.
+
+**To convert a local MKE 3 configuration for MKE 4:**
+
+Set the `--mke3-config` flag to convert a downloaded MKE 3 configuration file into
+a valid MKE 4 configuration file, as follows:
+
+```bash
+mkectl init --mke3-config /path/to/mke3-config.toml
+```