Merge pull request #213853 from MicrosoftDocs/release-ignite-mariner-v2

SyntaxC4 · web-flow · commit c3b3cb910a5b · 2022-10-06T08:35:02.000-07:00
[Ship Room] Release ignite mariner v2
diff --git a/articles/aks/TOC.yml b/articles/aks/TOC.yml
@@ -248,6 +248,8 @@
               href: start-stop-nodepools.md
             - name: Resize node pools
               href: resize-node-pool.md
+        - name: Use the Mariner container host
+          href: use-mariner.md
         - name: Deploy AKS with Terraform
           href: /azure/developer/terraform/create-k8s-cluster-with-tf-and-aks
           maintainContext: true
diff --git a/articles/aks/cluster-configuration.md b/articles/aks/cluster-configuration.md
@@ -123,6 +123,175 @@ az aks nodepool add --name ephemeral --cluster-name myAKSCluster --resource-grou
 
 If you want to create node pools with network-attached OS disks, you can do so by specifying `--node-osdisk-type Managed`.
 
+## Mariner OS
+
+Mariner can be deployed on AKS through Azure CLI or ARM templates.
+
+### Prerequisites
+
+1. You need the latest version of Azure CLI. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].
+2. You need the `aks-preview` Azure CLI extension for the ability to select the Mariner 2.0 operating system SKU. Run `az extension remove --name aks-preview` to clear any previous versions, then run `az extension add --name aks-preview`.
+3. If you don't already have kubectl installed, install it through Azure CLI using `az aks install-cli` or follow the [upstream instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).
+
+### Deploy an AKS Mariner cluster with Azure CLI
+
+Use the following example commands to create a Mariner cluster.
+
+```azurecli
+az group create --name MarinerTest --location eastus
+
+az aks create --name testMarinerCluster --resource-group MarinerTest --os-sku mariner
+
+az aks get-credentials --resource-group MarinerTest --name testMarinerCluster
+
+kubectl get pods --all-namespaces
+```
+
+### Deploy an AKS Mariner cluster with an ARM template
+
+To add Mariner to an existing ARM template, you need to add `"osSKU": "mariner"` and `"mode": "System"` to `agentPoolProfiles` and set the apiVersion to 2021-03-01 or newer (`"apiVersion": "2021-03-01"`). The following deployment uses the ARM template "marineraksarm.yml".
+
+```yml
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.1",
+  "parameters": {
+    "clusterName": {
+      "type": "string",
+      "defaultValue": "marinerakscluster",
+      "metadata": {
+        "description": "The name of the Managed Cluster resource."
+      }
+    },
+    "location": {
+      "type": "string",
+      "defaultValue": "[resourceGroup().location]",
+      "metadata": {
+        "description": "The location of the Managed Cluster resource."
+      }
+    },
+    "dnsPrefix": {
+      "type": "string",
+      "metadata": {
+        "description": "Optional DNS prefix to use with hosted Kubernetes API server FQDN."
+      }
+    },
+    "osDiskSizeGB": {
+      "type": "int",
+      "defaultValue": 0,
+      "minValue": 0,
+      "maxValue": 1023,
+      "metadata": {
+        "description": "Disk size (in GB) to provision for each of the agent pool nodes. This value ranges from 0 to 1023. Specifying 0 will apply the default disk size for that agentVMSize."
+      }
+    },
+    "agentCount": {
+      "type": "int",
+      "defaultValue": 3,
+      "minValue": 1,
+      "maxValue": 50,
+      "metadata": {
+        "description": "The number of nodes for the cluster."
+      }
+    },
+    "agentVMSize": {
+      "type": "string",
+      "defaultValue": "Standard_DS2_v2",
+      "metadata": {
+        "description": "The size of the Virtual Machine."
+      }
+    },
+    "linuxAdminUsername": {
+      "type": "string",
+      "metadata": {
+        "description": "User name for the Linux Virtual Machines."
+      }
+    },
+    "sshRSAPublicKey": {
+      "type": "string",
+      "metadata": {
+        "description": "Configure all linux machines with the SSH RSA public key string. Your key should include three parts, for example 'ssh-rsa AAAAB...snip...UcyupgH azureuser@linuxvm'"
+      }
+    },
+    "osType": {
+      "type": "string",
+      "defaultValue": "Linux",
+      "allowedValues": [
+        "Linux"
+      ],
+      "metadata": {
+        "description": "The type of operating system."
+      }
+    },
+    "osSKU": {
+      "type": "string",
+      "defaultValue": "mariner",
+      "allowedValues": [
+        "mariner",
+        "Ubuntu",
+      ],
+      "metadata": {
+        "description": "The Linux SKU to use."
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.ContainerService/managedClusters",
+      "apiVersion": "2021-03-01",
+      "name": "[parameters('clusterName')]",
+      "location": "[parameters('location')]",
+      "properties": {
+        "dnsPrefix": "[parameters('dnsPrefix')]",
+        "agentPoolProfiles": [
+          {
+            "name": "agentpool",
+            "mode": "System",
+            "osDiskSizeGB": "[parameters('osDiskSizeGB')]",
+            "count": "[parameters('agentCount')]",
+            "vmSize": "[parameters('agentVMSize')]",
+            "osType": "[parameters('osType')]",
+            "osSKU": "[parameters('osSKU')]",
+            "storageProfile": "ManagedDisks"
+          }
+        ],
+        "linuxProfile": {
+          "adminUsername": "[parameters('linuxAdminUsername')]",
+          "ssh": {
+            "publicKeys": [
+              {
+                "keyData": "[parameters('sshRSAPublicKey')]"
+              }
+            ]
+          }
+        }
+      },
+      "identity": {
+          "type": "SystemAssigned"
+      }
+    }
+  ],
+  "outputs": {
+    "controlPlaneFQDN": {
+      "type": "string",
+      "value": "[reference(parameters('clusterName')).fqdn]"
+    }
+  }
+}
+```
+
+Create this file on your system and fill it with the contents of the Mariner AKS YAML file.
+
+```azurecli
+az group create --name MarinerTest --location eastus
+
+az deployment group create --resource-group MarinerTest --template-file marineraksarm.yml --parameters clusterName=testMarinerCluster dnsPrefix=marineraks1 linuxAdminUsername=azureuser sshRSAPublicKey=`<contents of your id_rsa.pub>`
+
+az aks get-credentials --resource-group MarinerTest --name testMarinerCluster
+
+kubectl get pods --all-namespaces
+```
+
 ## Custom resource group name
 
 When you deploy an Azure Kubernetes Service cluster in Azure, a second resource group gets created for the worker nodes. By default, AKS will name the node resource group `MC_resourcegroupname_clustername_location`, but you can also provide your own name.
diff --git a/articles/aks/index.yml b/articles/aks/index.yml
@@ -26,6 +26,8 @@ landingContent:
             url: intro-kubernetes.md
       - linkListType: whats-new
         links:
+          - text: Mariner container host for AKS
+            url: use-mariner.md
           - text: Vertical Pod Autoscaler (preview)
             url: vertical-pod-autoscaler.md
           - text: Workload identity (preview)
diff --git a/articles/aks/intro-kubernetes.md b/articles/aks/intro-kubernetes.md
@@ -83,6 +83,12 @@ AKS supports the creation of Intel SGX-based, confidential computing node pools
 
 For more information, see [Confidential computing nodes on AKS][conf-com-node].
 
+### Mariner nodes
+
+Mariner is an open-source Linux distribution created by Microsoft, and it’s now available for preview as a container host on Azure Kubernetes Service (AKS). The Mariner container host provides reliability and consistency from cloud to edge across the AKS, AKS-HCI, and Arc products. You can deploy Mariner node pools in a new cluster, add Mariner node pools to your existing Ubuntu clusters, or migrate your Ubuntu nodes to Mariner nodes.
+
+For more information, see [Use the Mariner container host on Azure Kubernetes Service (AKS)](use-mariner.md)
+
 ### Storage volume support
 
 To support application workloads, you can mount static or dynamic storage volumes for persistent data. Depending on the number of connected pods expected to share the storage volumes, you can use storage backed by either:
diff --git a/articles/aks/use-mariner.md b/articles/aks/use-mariner.md
@@ -0,0 +1,69 @@
+---
+
+title: Use the Mariner container host on Azure Kubernetes Service (AKS)
+description: Learn how to use the Mariner container host on Azure Kubernetes Service (AKS)
+services: container-service
+ms.topic: article
+ms.date: 09/22/2022
+---
+
+# Use the Mariner container host on Azure Kubernetes Service (AKS)
+
+Mariner is an open-source Linux distribution created by Microsoft, and it’s now available for preview as a container host on Azure Kubernetes Service (AKS). The Mariner container host provides reliability and consistency from cloud to edge across the AKS, AKS-HCI, and Arc products. You can deploy Mariner node pools in a new cluster, add Mariner node pools to your existing Ubuntu clusters, or migrate your Ubuntu nodes to Mariner nodes. To learn more about Mariner, see the [Mariner documentation][mariner-doc].
+
+## Why use Mariner
+
+The Mariner container host on AKS uses a native AKS image that provides one place to do all Linux development. Every package is built from source and validated, ensuring your services run on proven components. Mariner is lightweight, only including the necessary set of packages needed to run container workloads. It provides a reduced attack surface and eliminates patching and maintenance of unnecessary packages. At Mariner's base layer, it has a Microsoft hardened kernel tuned for Azure. Learn more about the [key capabilities of Mariner][mariner-capabilities].
+
+## How to use Mariner on AKS
+
+To get started using Mariner on AKS, see:
+
+* [Creating a cluster with Mariner][mariner-cluster-config]
+* [Add a Mariner node pool to your existing cluster][mariner-node-pool]
+* [Ubuntu to Mariner migration][ubuntu-to-mariner]
+
+## How to upgrade Mariner nodes
+
+We recommend keeping your clusters up to date and secured by enabling automatic upgrades for your cluster. To enable automatic upgrades, see:
+
+* [Automatically upgrade an Azure Kubernetes Service (AKS) cluster][auto-upgrade-aks]
+* [Deploy kured in an AKS cluster][kured]
+
+To manually upgrade the node-image on a cluster, you can run `az aks nodepool upgrade`:
+
+```azurecli
+az aks nodepool upgrade \
+    --resource-group myResourceGroup \
+    --cluster-name myAKSCluster \
+    --name myNodePool \
+    --node-image-only
+```
+
+## Regional availability
+
+Mariner is available for use in the same regions as AKS.
+
+## Limitations
+
+Mariner currently has the following limitations:
+
+* Mariner does not yet have image SKUs for GPU, ARM64, SGX, or FIPS.
+* Mariner does not yet have FedRAMP, FIPS, or CIS certification.
+* Mariner cannot yet be deployed through Azure portal or Terraform.
+* Some vulnerability tools may not support Mariner yet.
+* The Mariner container host is a Gen 2 image. Mariner does not plan to offer a Gen 1 SKU.
+* Node configurations are not yet supported.
+* Mariner is not yet supported in GitHub actions.
+* Mariner does not support AppArmor. Support for SELinux can be manually configured.
+* Some addons, extensions, and open-source integrations may not be supported yet on Mariner. Azure Monitor, Grafana, Helm, Key Vault, and Container Insights are confirmed to be supported.
+* AKS diagnostics does not yet support Mariner.
+
+<!-- LINKS - Internal -->
+[mariner-doc]: https://microsoft.github.io/CBL-Mariner/docs/#cbl-mariner-linux
+[mariner-capabilities]: https://microsoft.github.io/CBL-Mariner/docs/#key-capabilities-of-cbl-mariner-linux
+[mariner-cluster-config]: cluster-configuration.md
+[mariner-node-pool]: use-multiple-node-pools.md
+[ubuntu-to-mariner]: use-multiple-node-pools.md
+[auto-upgrade-aks]: auto-upgrade-cluster.md
+[kured]: node-updates-kured.md
diff --git a/articles/aks/use-multiple-node-pools.md b/articles/aks/use-multiple-node-pools.md
@@ -135,6 +135,38 @@ az aks nodepool add \
     --node-vm-size Standard_Dpds_v5
 ```
 
+### Add a Mariner node pool
+
+Mariner is an open-source Linux distribution available as an AKS container host. It provides high reliability, security, and consistency. Mariner only includes the minimal set of packages needed for running container workloads, which improves boot times and overall performance.
+
+You can add a Mariner node pool into your existing cluster using the `az aks nodepool add` command and specifying `--os-sku mariner`.
+
+```azurecli
+az aks nodepool add \
+    --resource-group myResourceGroup \
+    --cluster-name myAKSCluster \
+    --os-sku mariner
+```
+
+### Migrate Ubuntu nodes to Mariner
+
+Use the following instructions to migrate your Ubuntu nodes to Mariner nodes.
+
+1. Add a Mariner node pool into your existing cluster using the `az aks nodepool add` command and specifying `--os-sku mariner`.
+
+> [!NOTE]
+> When adding a new Mariner node pool, you need to add at least one as `--mode System`. Otherwise, AKS won't allow you to delete your existing Ubuntu node pool.
+2. [Cordon the existing Ubuntu nodes][cordon-and-drain].
+3. [Drain the existing Ubuntu nodes][drain-nodes].
+4. Remove the existing Ubuntu nodes using the `az aks delete` command.
+
+```azurecli
+az aks nodepool delete \
+    --resource-group myResourceGroup \
+    --cluster-name myAKSCluster \
+    --name myNodePool
+```
+
 ### Add a node pool with a unique subnet
 
 A workload may require splitting a cluster's nodes into separate pools for logical isolation. This isolation can be supported with separate subnets dedicated to each node pool in the cluster. This can address requirements such as having non-contiguous virtual network address space to split across node pools.
@@ -833,3 +865,4 @@ az group delete --name myResourceGroup2 --yes --no-wait
 [use-labels]: use-labels.md
 [cordon-and-drain]: resize-node-pool.md#cordon-the-existing-nodes
 [internal-lb-different-subnet]: internal-lb.md#specify-a-different-subnet
+[drain-nodes]: resize-node-pool.md#drain-the-existing-nodes
