Skip to content

Commit e4eb3b4

Browse files
author
naman-msft
committed
added flatcar doc in exec docs
1 parent 175804f commit e4eb3b4

File tree

4 files changed

+521
-0
lines changed

4 files changed

+521
-0
lines changed

‎scenarios/metadata.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1190,5 +1190,17 @@
11901190
"configurations": {
11911191
"permissions": []
11921192
}
1193+
},
1194+
{
1195+
"status": "active",
1196+
"key": "upstream/FlatcarOnAzure/flatcar-on-azure.md",
1197+
"title": "Running Flatcar Container Linux on Microsoft Azure",
1198+
"description": "Deploy Flatcar Container Linux in Microsoft Azure by creating resource groups and using official marketplace images.",
1199+
"stackDetails": [
1200+
],
1201+
"sourceUrl": "https://raw.githubusercontent.com/MicrosoftDocs/executable-docs/main/scenarios/upstream/FlatcarOnAzure/flatcar-on-azure.md",
1202+
"documentationUrl": "https://www.flatcar.org/docs/latest/installing/cloud/azure/",
1203+
"configurations": {
1204+
}
11931205
}
11941206
]

‎scenarios/upstream/FlatcarOnAzure/flatcar-on-azure.md

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: 'Running Flatcar Container Linux on Microsoft Azure'
3+
description: 'Deploy Flatcar Container Linux in Microsoft Azure by creating resource groups and using official marketplace images.'
4+
ms.topic: article
5+
ms.date: 03/17/2025
6+
author: naman-msft
7+
ms.author: namanparikh
8+
ms.custom: innovation-engine, azure, flatcar
9+
---
10+
11+
## Creating resource group via Microsoft Azure CLI
12+
13+
Follow the [installation and configuration guides][azure-cli] for the Microsoft Azure CLI to set up your local installation.
14+
15+
Instances on Microsoft Azure must be created within a resource group. Create a new resource group with the following command:
16+
17+
```bash
18+
export RANDOM_SUFFIX=$(openssl rand -hex 3)
19+
export RESOURCE_GROUP_NAME="group-1$RANDOM_SUFFIX"
20+
export REGION="WestUS2"
21+
az group create --name $RESOURCE_GROUP_NAME --location $REGION
22+
```
23+
24+
Results:
25+
26+
<!-- expected_similarity=0.3 -->
27+
```json
28+
{
29+
"id": "/subscriptions/xxxxx/resourceGroups/group-1xxx",
30+
"location": "WestUS2",
31+
"managedBy": null,
32+
"name": "group-1xxx",
33+
"properties": {
34+
"provisioningState": "Succeeded"
35+
},
36+
"tags": null,
37+
"type": "Microsoft.Resources/resourceGroups"
38+
}
39+
```
40+
41+
Now that you have a resource group, you can choose a channel of Flatcar Container Linux you would like to install.
42+
43+
## Using the official image from the Marketplace
44+
45+
Official Flatcar Container Linux images for all channels are available in the Marketplace.
46+
Flatcar is published by the `kinvolk` publisher on Marketplace.
47+
Flatcar Container Linux is designed to be [updated automatically][update-docs] with different schedules per channel. Updating
48+
can be [disabled][reboot-docs], although it is not recommended to do so. The [release notes][release-notes] contain
49+
information about specific features and bug fixes.
50+
51+
The following command will query for the latest image URN specifier through the Azure CLI:
52+
53+
```bash
54+
az vm image list --all -p kinvolk -f flatcar -s stable-gen2 --query '[-1]'
55+
```
56+
57+
Results:
58+
59+
<!-- expected_similarity=0.3 -->
60+
61+
```json
62+
{
63+
"architecture": "x64",
64+
"offer": "flatcar-container-linux-free",
65+
"publisher": "kinvolk",
66+
"sku": "stable-gen2",
67+
"urn": "kinvolk:flatcar-container-linux-free:stable-gen2:3815.2.0",
68+
"version": "3815.2.0"
69+
}
70+
```
71+
72+
Use the offer named `flatcar-container-linux-free`; there is also a legacy offer called `flatcar-container-linux` with the same contents.
73+
The SKU, which is the third element of the image URN, relates to one of the release channels and also depends on whether to use Hyper-V Generation 1 or 2 VMs.
74+
Generation 2 instance types use UEFI boot and should be preferred, the SKU matches the pattern `<channel>-gen`: `alpha-gen2`, `beta-gen2` or `stable-gen2`.
75+
For Generation 1 instance types drop the `-gen2` from the SKU: `alpha`, `beta` or `stable`.
76+
Note: _`az vm image list -s` flag matches parts of the SKU, which means that `-s stable` will return both the `stable` and `stable-gen2` SKUs._
77+
78+
Before being able to use the offers, you may need to accept the legal terms once, which is demonstrated for `flatcar-container-linux-free` and `stable-gen2`:
79+
80+
```bash
81+
az vm image terms show --publish kinvolk --offer flatcar-container-linux-free --plan stable-gen2
82+
az vm image terms accept --publish kinvolk --offer flatcar-container-linux-free --plan stable-gen2
83+
```
84+
85+
For quick tests the official Azure CLI also supports an alias for the latest Flatcar stable image:
86+
87+
```bash
88+
az vm create --name node-1 --resource-group $RESOURCE_GROUP_NAME --admin-username core --image FlatcarLinuxFreeGen2 --generate-ssh-keys
89+
```
90+
91+
Results:
92+
93+
<!-- expected_similarity=0.3 -->
94+
95+
```json
96+
{
97+
"fqdns": null,
98+
"id": "/subscriptions/xxxxx/resourceGroups/group-1xxx/providers/Microsoft.Compute/virtualMachines/node-1",
99+
"location": "WestUS2",
100+
"name": "node-1",
101+
"powerState": "VM running",
102+
"provisioningState": "Succeeded",
103+
"resourceGroup": "group-1xxx",
104+
"zones": null
105+
}
106+
```
107+
108+
### CoreVM
109+
110+
Flatcar images are also published under an offer called `flatcar-container-linux-corevm-amd64`. This offer does not require accepting image terms and does not require specifying plan information when creating instances or building derived images. The content of the images matches the other offers.
111+
112+
```bash
113+
az vm image list --all -p kinvolk -f flatcar-container-linux-corevm-amd64 -s stable-gen2 --query '[-1]'
114+
```
115+
116+
Results:
117+
118+
<!-- expected_similarity=0.3 -->
119+
120+
```json
121+
{
122+
"architecture": "x64",
123+
"offer": "flatcar-container-linux-corevm-amd64",
124+
"publisher": "kinvolk",
125+
"sku": "stable-gen2",
126+
"urn": "kinvolk:flatcar-container-linux-corevm-amd64:stable-gen2:3815.2.0",
127+
"version": "3815.2.0"
128+
}
129+
```
130+
131+
### ARM64
132+
133+
Arm64 images are published under the offer called `flatcar-container-linux-corevm`. These are Generation 2 images—the only supported option on Azure for Arm64 instances—so the SKU contains only the release channel name without the `-gen2` suffix: `alpha`, `beta`, or `stable`. This offer has the same properties as the `CoreVM` offer described above.
134+
135+
```bash
136+
az vm image list --all --architecture arm64 -p kinvolk -f flatcar -s stable --query '[-1]'
137+
```
138+
139+
Results:
140+
141+
<!-- expected_similarity=0.3 -->
142+
143+
```json
144+
{
145+
"architecture": "Arm64",
146+
"offer": "flatcar-container-linux-corevm",
147+
"publisher": "kinvolk",
148+
"sku": "stable",
149+
"urn": "kinvolk:flatcar-container-linux-corevm:stable:3815.2.0",
150+
"version": "3815.2.0"
151+
}
152+
```
153+
154+
### Flatcar Pro Images
155+
156+
Flatcar Pro images were paid marketplace images that came with commercial support and extra features. All the previous features of Flatcar Pro images, such as support for NVIDIA GPUs, are now available to all users in standard Flatcar marketplace images.
157+
158+
### Plan information for building your image from the Marketplace Image
159+
160+
When building an image based on the Marketplace image you sometimes need to specify the original plan. The plan name is the image SKU (for example, `stable`), the plan product is the image offer (for example, `flatcar-container-linux-free`), and the plan publisher is the same (`kinvolk`).
161+
162+
## Community Shared Image Gallery
163+
164+
While the Marketplace images are recommended, it sometimes might be easier or required to use Shared Image Galleries—for example, when using Packer for Kubernetes CAPI images.
165+
166+
A public Shared Image Gallery hosts recent Flatcar Stable images for amd64. Here is how to list the image definitions (for now you will only find `flatcar-stable-amd64`) and the image versions they provide:
167+
168+
```bash
169+
az sig image-definition list-community --public-gallery-name flatcar-23485951-527a-48d6-9d11-6931ff0afc2e --location westeurope
170+
az sig image-version list-community --public-gallery-name flatcar-23485951-527a-48d6-9d11-6931ff0afc2e --gallery-image-definition flatcar-stable-amd64 --location westeurope
171+
```
172+
173+
A second gallery, `flatcar4capi-742ef0cb-dcaa-4ecb-9cb0-bfd2e43dccc0`, exists for prebuilt Kubernetes CAPI images. It has image definitions for each CAPI version—for example, `flatcar-stable-amd64-capi-v1.26.3` provides recent Flatcar Stable versions.
174+
175+
[flatcar-user]: https://groups.google.com/forum/#!forum/flatcar-linux-user
176+
[etcd-docs]: https://etcd.io/docs
177+
[quickstart]: ../
178+
[reboot-docs]: ../../setup/releases/update-strategies
179+
[azure-cli]: https://docs.microsoft.com/en-us/cli/azure/overview
180+
[butane-configs]: ../../provisioning/config-transpiler
181+
[irc]: irc://irc.freenode.org:6667/#flatcar
182+
[docs]: ../../
183+
[resource-group]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#naming-rules-and-restrictions
184+
[storage-account]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview#naming-storage-accounts
185+
[azure-flatcar-image-upload]: https://github.com/flatcar/flatcar-cloud-image-uploader
186+
[release-notes]: https://flatcar.org/releases
187+
[update-docs]: ../../setup/releases/update-strategies

‎tools/flatcar.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Running Flatcar Container Linux on Microsoft Azure
3+
linktitle: Running on Microsoft Azure
4+
weight: 10
5+
aliases:
6+
- ../../os/booting-on-azure
7+
- ../../cloud-providers/booting-on-azure
8+
---
9+
10+
## Creating resource group via Microsoft Azure CLI
11+
12+
Follow the [installation and configuration guides][azure-cli] for the Microsoft Azure CLI to set up your local installation.
13+
14+
Instances on Microsoft Azure must be created within a resource group. Create a new resource group with the following command:
15+
16+
```bash
17+
az group create --name group-1 --location <location>
18+
```
19+
20+
Now that you have a resource group, you can choose a channel of Flatcar Container Linux you would like to install.
21+
22+
## Using the official image from the Marketplace
23+
24+
Official Flatcar Container Linux images for all channels are available in the Marketplace.
25+
Flatcar is published by the `kinvolk` publisher on Marketplace.
26+
Flatcar Container Linux is designed to be [updated automatically][update-docs] with different schedules per channel. Updating
27+
can be [disabled][reboot-docs], although it is not recommended to do so. The [release notes][release-notes] contain
28+
information about specific features and bug fixes.
29+
30+
The following command will create a single instance through the Azure CLI.
31+
32+
```bash
33+
az vm image list --all -p kinvolk -f flatcar -s stable-gen2 --query '[-1]' # Query the image name urn specifier
34+
```
35+
36+
```json
37+
{
38+
"architecture": "x64",
39+
"offer": "flatcar-container-linux-free",
40+
"publisher": "kinvolk",
41+
"sku": "stable-gen2",
42+
"urn": "kinvolk:flatcar-container-linux-free:stable-gen2:3815.2.0",
43+
"version": "3815.2.0"
44+
}
45+
46+
Use the offer named `flatcar-container-linux-free`, there is also a legacy offer called `flatcar-container-linux` with the same contents.
47+
The SKU, which is the third element of the image URN, relates to one of the release channels and also depends on whether to use Hyper-V Generation 1 or 2 VM.
48+
Generation 2 instance types use UEFI boot and should be preferred, the SKU matches the pattern `<channel>-gen`: `alpha-gen2`, `beta-gen2` or `stable-gen2`.
49+
For Generation 1 instance types drop the `-gen2` from the SKU: `alpha`, `beta` or `stable`.
50+
Note: _`az vm image list -s` flag matches parts of the SKU, which means that `-s stable` will return both the `stable` and `stable-gen2` SKUs._
51+
52+
Before being able to use the offers, you may need to accept the legal terms once, here done for `flatcar-container-linux-free` and `stable-gen2`:
53+
54+
```bash
55+
az vm image terms show --publish kinvolk --offer flatcar-container-linux-free --plan stable-gen2
56+
az vm image terms accept --publish kinvolk --offer flatcar-container-linux-free --plan stable-gen2
57+
```
58+
59+
For quick tests the official Azure CLI also supports an alias for the latest Flatcar stable image:
60+
```bash
61+
az vm create --name node-1 --resource-group group-1 --admin-username core --user-data config.ign --image FlatcarLinuxFreeGen2
62+
```
63+
64+
### CoreVM
65+
66+
Flatcar images are also published under an offer called `flatcar-container-linux-corevm-amd64`. This offer does not require accepting image terms and does not require specifying plan information when creating instances or building derived images. The content of the images matches the other offers.
67+
```bash
68+
az vm image list --all -p kinvolk -f flatcar-container-linux-corevm-amd64 -s stable-gen2 --query '[-1]'
69+
```
70+
71+
```json
72+
{
73+
"architecture": "x64",
74+
"offer": "flatcar-container-linux-corevm-amd64",
75+
"publisher": "kinvolk",
76+
"sku": "stable-gen2",
77+
"urn": "kinvolk:flatcar-container-linux-corevm-amd64:stable-gen2:3815.2.0",
78+
"version": "3815.2.0"
79+
}
80+
```
81+
82+
### ARM64
83+
Arm64 images are published under the offer called `flatcar-container-linux-corevm`. These are Generation 2 images, the only supported option on Azure for Arm64 instances, so the SKU contains only the release channel name without the `-gen2` suffix: `alpha`, `beta`, `stable`. This offer has the same properties as the `CoreVM` offer described above.
84+
85+
```bash
86+
az vm image list --all --architecture arm64 -p kinvolk -f flatcar -s stable --query '[-1]'
87+
```
88+
89+
```json
90+
{
91+
"architecture": "Arm64",
92+
"offer": "flatcar-container-linux-corevm",
93+
"publisher": "kinvolk",
94+
"sku": "stable",
95+
"urn": "kinvolk:flatcar-container-linux-corevm:stable:3815.2.0",
96+
"version": "3815.2.0"
97+
}
98+
```
99+
100+
101+
102+
### Flatcar Pro Images
103+
104+
Flatcar Pro images were paid marketplace images that came with commercial support and extra features. All the previous features of Flatcar Pro images, such as support for NVIDIA GPUs, are now available to all users in standard Flatcar marketplace images.
105+
106+
### Plan information for building your image from the Marketplace Image
107+
108+
When building an image based on the Marketplace image you sometimes need to specify the original plan. The plan name is the image SKU, e.g., `stable`, the plan product is the image offer, e.g., `flatcar-container-linux-free`, and the plan publisher is the same (`kinvolk`).
109+
110+
## Community Shared Image Gallery
111+
112+
While the Marketplace images are recommended, it sometimes might be easier or required to use Shared Image Galleries, e.g., when using Packer for Kubernetes CAPI images.
113+
114+
A public Shared Image Gallery hosts recent Flatcar Stable images for amd64. Here is how to show the image definitions (for now you will only find `flatcar-stable-amd64`) and the image versions they provide:
115+
116+
```bash
117+
az sig image-definition list-community --public-gallery-name flatcar-23485951-527a-48d6-9d11-6931ff0afc2e --location westeurope
118+
az sig image-version list-community --public-gallery-name flatcar-23485951-527a-48d6-9d11-6931ff0afc2e --gallery-image-definition flatcar-stable-amd64 --location westeurope
119+
```
120+
121+
A second gallery `flatcar4capi-742ef0cb-dcaa-4ecb-9cb0-bfd2e43dccc0` exists for prebuilt Kubernetes CAPI images. It has image definitions for each CAPI version, e.g., `flatcar-stable-amd64-capi-v1.26.3` which provides recent Flatcar Stable versions.
122+
123+
[flatcar-user]: https://groups.google.com/forum/#!forum/flatcar-linux-user
124+
[etcd-docs]: https://etcd.io/docs
125+
[quickstart]: ../
126+
[reboot-docs]: ../../setup/releases/update-strategies
127+
[azure-cli]: https://docs.microsoft.com/en-us/cli/azure/overview
128+
[butane-configs]: ../../provisioning/config-transpiler
129+
[irc]: irc://irc.freenode.org:6667/#flatcar
130+
[docs]: ../../
131+
[resource-group]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#naming-rules-and-restrictions
132+
[storage-account]: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview#naming-storage-accounts
133+
[azure-flatcar-image-upload]: https://github.com/flatcar/flatcar-cloud-image-uploader
134+
[release-notes]: https://flatcar.org/releases
135+
[update-docs]: ../../setup/releases/update-strategies

0 commit comments

Comments
 (0)