Document Azure usage (#812)

* feat(azure): create overview documention for running kubefirst on azure * feat(azure): add credits * feat(azure): add faq * feat(azure): add gitops-catalog docs * feat(azure): document cluster deprovisioning * feat(azure): add cli installation instructions * feat(azure): add cluster manager and repos * feat(azure): add the explore docs * feat: add azure to navbar for v.next --------- Co-authored-by: Frédéric Harper <[email protected]>
konstructio · Nov 13, 2024 · 67fedb0 · 67fedb0
1 parent 405d2b5
commit 67fedb0
Show file tree

Hide file tree

Showing 36 changed files with 3,845 additions and 8 deletions.
diff --git a/.vale/Custom/ignore.txt b/.vale/Custom/ignore.txt
@@ -18,6 +18,7 @@ cronjob
 # E
 ecr
 eks
+Entra
 
 # F
 

diff --git a/docs/azure/credits.mdx b/docs/azure/credits.mdx
@@ -0,0 +1,9 @@
+---
+title: Credits
+description: credit to all the awesome open source projects
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import CommonCredits from "../common/credits.mdx";
+
+<CommonCredits />
diff --git a/docs/azure/deprovision.mdx b/docs/azure/deprovision.mdx
@@ -0,0 +1,12 @@
+---
+hide_title: true
+sidebar_label: Deprovision
+description: how to deprovision your kubefirst platform
+keywords:
+  - aws
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import Deprovision from '../common/deprovision.mdx';
+
+<Deprovision />
diff --git a/docs/azure/explore/argocd.mdx b/docs/azure/explore/argocd.mdx
@@ -0,0 +1,10 @@
+---
+title: Argo CD
+sidebar_position: 1
+---
+
+# Azure - Argo CD
+
+import ExploreArgocd from "../../common/argocd.mdx";
+
+<ExploreArgocd cloud="Azure" />
diff --git a/docs/azure/explore/gitops.mdx b/docs/azure/explore/gitops.mdx
@@ -0,0 +1,10 @@
+---
+title: GitOps
+sidebar_position: 2
+---
+
+import ExploreGitOps from "../../common/gitops.mdx";
+
+# Azure - GitOps
+
+<ExploreGitOps />
diff --git a/docs/azure/explore/metaphor.mdx b/docs/azure/explore/metaphor.mdx
@@ -0,0 +1,10 @@
+---
+title: Metaphor
+sidebar_position: 3
+---
+
+import ExploreMetaphor from "../../common/metaphor.mdx";
+
+# Azure - Metaphor
+
+<ExploreMetaphor/>
diff --git a/docs/azure/explore/telemetry.mdx b/docs/azure/explore/telemetry.mdx
@@ -0,0 +1,10 @@
+---
+title: Telemetry
+sidebar_position: 7
+---
+
+import ExploreTelemetry from "../../common/telemetry.mdx";
+
+# Azure - Telemetry
+
+<ExploreTelemetry/>
diff --git a/docs/azure/explore/terraform.mdx b/docs/azure/explore/terraform.mdx
@@ -0,0 +1,10 @@
+---
+title: Terraform & Atlantis
+sidebar_position: 4
+---
+
+import ExploreTerraform from "../../common/terraform.mdx";
+
+# Azure - Terraform & Atlantis
+
+<ExploreTerraform/>
diff --git a/docs/azure/explore/user-creation.mdx b/docs/azure/explore/user-creation.mdx
@@ -0,0 +1,10 @@
+---
+title: Users Management
+sidebar_position: 5
+---
+
+import UserCreation from "../../common/users.mdx";
+
+# Azure - Users Management
+
+<UserCreation cloud="azure" />
diff --git a/docs/azure/explore/vault.mdx b/docs/azure/explore/vault.mdx
@@ -0,0 +1,10 @@
+---
+title: Vault
+sidebar_position: 6
+---
+
+import ExploreVault from "../../common/vault.mdx";
+
+# Azure - Vault
+
+<ExploreVault/>
diff --git a/docs/azure/faq.mdx b/docs/azure/faq.mdx
@@ -0,0 +1,17 @@
+---
+title: FAQ
+description: frequently asked quesitons about the kubefirst platform
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import FAQ from "../common/faq.mdx";
+
+<FAQ cloud="Azure" />
+
+## Azure
+
+### What authentication methods do you support?
+
+Currently, the only supported authentication method is a service principal with a client secret. Support for service principals with certificates is likely to be supported in the future. Please see [konstructio/kubefirst#2319](https://github.com/konstructio/kubefirst/issues/2319) for details and up-vote if you depend on this feature to use Kubefirst.
+
+There are no plans to support authentication without a service principal.
diff --git a/docs/azure/gitops-catalog.mdx b/docs/azure/gitops-catalog.mdx
@@ -0,0 +1,14 @@
+---
+hide_title: true
+sidebar_label: GitOps Catalog
+description: using the kubefirst gitops catalog
+keywords:
+  - aws
+image: 'https://kubefirst.konstruct.io/docs/img/kubefirst.svg'
+---
+
+import GitOpsCatalog from '../common/gitops-catalog.mdx';
+
+# Azure - GitOps Catalog
+
+<GitOpsCatalog />
diff --git a/docs/azure/overview.mdx b/docs/azure/overview.mdx
@@ -0,0 +1,59 @@
+---
+sidebar_label: Overview
+sidebar_position: 1
+description: an overview of kubefirst on an Azure kubernetes cluster
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import styles from "../stylesheets/tabs.module.css";
+import CommonProvisionProcess from "../common/partials/common/_provision-process.mdx";
+import GitHubOverview from '../azure/partials/github/_overview.mdx';
+import GitLabOverview from '../azure/partials/gitlab/_overview.mdx';
+import KnownLimitations from "../common/known-limitations.mdx";
+import AzureLogo from '../img/azure/logo.svg';
+import GitHubLogo from '../common/components/GitHubLogo.jsx'
+import GitLabLogo from '../common/components/GitLabLogo.jsx'
+
+<div class="cloud_logo">
+  <AzureLogo width="200px" alt="Azure Logo" />
+</div>
+
+# Overview
+
+:::caution
+
+Azure is in beta. Use at your own risk.
+
+:::
+
+The Azure provisioning process will:
+<CommonProvisionProcess firstitem="Create a Kubernetes management cluster in the Azure cloud."/>
+
+<Tabs groupId="git_provider" defaultValue="github" queryString>
+  <TabItem attributes={{ className: styles.github }} value="github" label={ <GitHubLogo /> }>
+
+    ![Installation Diagram](../img/azure/github/installation-diagram-light.svg#light-mode)![Installation Diagram](../img/azure/github/installation-diagram-dark.svg#dark-mode)
+
+    ## Applications
+    <GitHubOverview />
+
+  </TabItem>
+  <TabItem value="gitlab" attributes={{ className: styles.gitlab }} label={ <GitLabLogo /> }>
+
+    ![Installation Diagram](../img/azure/gitlab/installation-diagram-light.svg#light-mode)![Installation Diagram](../img/azure/gitlab/installation-diagram-dark.svg#dark-mode)
+
+    ## Applications
+    <GitLabOverview />
+  </TabItem>
+</Tabs>
+
+## Known Limitations
+
+<KnownLimitations />
+
+## Azure Specific
+
+- Azure is still in beta, but should be usable in production
+- Workload clusters are not available yet
diff --git a/docs/azure/partials/common/_dns-resource-group.mdx b/docs/azure/partials/common/_dns-resource-group.mdx
@@ -0,0 +1 @@
+The `dns-azure-resource-group` is only required if using Azure as your DNS provider. This is the name of the resource group where the [DNS Zone](https://learn.microsoft.com/en-us/azure/dns/dns-zones-records) resource is provisioned.
diff --git a/docs/azure/partials/common/_get-kubeconfig.mdx b/docs/azure/partials/common/_get-kubeconfig.mdx
@@ -0,0 +1,3 @@
+```shell
+az aks get-credentials --resource-group <my-cluster> --name <my-cluster>
+```
diff --git a/docs/azure/partials/common/_install-azure-cli.mdx b/docs/azure/partials/common/_install-azure-cli.mdx
@@ -0,0 +1,5 @@
+```shell
+brew install azure-cli
+```
+
+More information in the [Azure documentation](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).
diff --git a/docs/azure/partials/common/_prerequisites.mdx b/docs/azure/partials/common/_prerequisites.mdx
@@ -0,0 +1,18 @@
+### Azure Prerequisites
+
+For kubefirst to be able to provision your Azure cloud resources:
+
+- An [Azure account](https://portal.azure.com) in which you are an account owner.
+- A publicly routable [DNS zone](https://learn.microsoft.com/en-us/azure/dns/dns-zones-records).
+- A [Microsoft Entra app and service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal) with `Owner` permissions on your subscription.
+
+#### Environment variables
+
+Azure authentication requires the following environment variables to be set:
+
+| Variable | Description |
+| --- | --- |
+| `ARM_CLIENT_ID` | The unique ID for your [service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application) |
+| `ARM_CLIENT_SECRET` | The secret for your [service principal](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret) |
+| `ARM_SUBSCRIPTION_ID` | The unique ID for your [Azure subscription](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-azure-subscription) |
+| `ARM_TENANT_ID` | The unique ID for your [Microsoft Entra tenant](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-microsoft-entra-tenant) |
diff --git a/docs/azure/partials/github/_cluster-create.mdx b/docs/azure/partials/github/_cluster-create.mdx
@@ -0,0 +1,24 @@
+import CloudflareDNS from "../../../common/partials/common/_cloudflare-dns.mdx";
+import DNSResourceGroup from "../../partials/common/_dns-resource-group.mdx"
+
+## Create your new kubefirst cluster
+
+Adjust the following command with your GitHub and Azure tokens in addition to the appropriate values for your new platform.
+
+```shell
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
+export ARM_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_SUBSCRIPTION_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_TENANT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+kubefirst beta azure create \
+  --alerts-email [email protected] \
+  --github-org your-github-org \
+  --domain-name your-domain.io \
+  --cluster-name kubefirst \
+  --dns-azure-resource-group <dns-resource-group>
+```
+
+<DNSResourceGroup />
+<CloudflareDNS />
diff --git a/docs/azure/partials/github/_overview.mdx b/docs/azure/partials/github/_overview.mdx
@@ -0,0 +1,16 @@
+`kubefirst beta azure create` provisions a local [Azure](https://azure.microsoft.com) Kubernetes cluster to host your cloud native environment locally.
+
+Your Azure cluster will include:
+
+| Application                     | Description                                                                 |
+|---------------------------------|-----------------------------------------------------------------------------|
+| Argo CD                         | GitOps Continuous Delivery                                                  |
+| Argo Workflows                  | Application Continuous Integration                                          |
+| Atlantis                        | Terraform Workflow Automation                                               |
+| cert-manager                    | Certificate Automation Utility                                              |
+| ChartMuseum                     | Helm Chart Registry                                                         |
+| External Secrets Operators      | Syncs Kubernetes secrets with Vault secrets                                 |
+| GitHub Action Runner Controller | GitHub Self-Hosted CI Executor                                              |
+| HashiCorp Vault                 | Secrets Management                                                          |
+| Metaphor                        | (development, staging, production) instance of sample Next.js app           |
+| Ingress Nginx                   | Ingress Controller                                                          |
diff --git a/docs/azure/partials/gitlab/_cluster-create.mdx b/docs/azure/partials/gitlab/_cluster-create.mdx
@@ -0,0 +1,25 @@
+import CloudflareDNS from "../../../common/partials/common/_cloudflare-dns.mdx";
+import DNSResourceGroup from "../../partials/common/_dns-resource-group.mdx"
+
+## Create your new kubefirst cluster
+
+Adjust the following command with your GitHub and Azure tokens in addition to the appropriate values for your new platform.
+
+```shell
+export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx
+export ARM_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_SUBSCRIPTION_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+export ARM_TENANT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+kubefirst beta azure create \
+  --alerts-email [email protected] \
+  --git-provider gitlab \
+  --gitlab-group your-fully-qualified-gitlab-group/or-sub-group  \
+  --domain-name your-domain.io \
+  --cluster-name kubefirst \
+  --dns-azure-resource-group <dns-resource-group>
+```
+
+<DNSResourceGroup />
+<CloudflareDNS />
diff --git a/docs/azure/partials/gitlab/_overview.mdx b/docs/azure/partials/gitlab/_overview.mdx
@@ -0,0 +1,16 @@
+`kubefirst beta azure create` provisions a local [Azure](https://azure.microsoft.com) Kubernetes cluster to host your cloud native environment locally.
+
+Your Azure cluster will include:
+
+| Application                     | Description                                                                 |
+|---------------------------------|-----------------------------------------------------------------------------|
+| Argo CD                         | GitOps Continuous Delivery                                                  |
+| Argo Workflows                  | Application Continuous Integration                                          |
+| Atlantis                        | Terraform Workflow Automation                                               |
+| cert-manager                    | Certificate Automation Utility                                              |
+| ChartMuseum                     | Helm Chart Registry                                                         |
+| External Secrets Operators      | Syncs Kubernetes secrets with Vault secrets                                 |
+| GitLab Runner                   | GitLab Self-Hosted CI Executor                                              |
+| HashiCorp Vault                 | Secrets Management                                                          |
+| Metaphor                        | (development, staging, production) instance of sample Next.js app           |
+| Ingress Nginx                   | Ingress Controller                                                          |
diff --git a/docs/azure/quick-start/cluster-management.mdx b/docs/azure/quick-start/cluster-management.mdx
@@ -0,0 +1,10 @@
+---
+title: Cluster Management
+sidebar_position: 3
+description: cluster creation and lifecycle management powered by gitops
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import CLUSTERS from "../../common/clusters.mdx";
+
+<CLUSTERS />
diff --git a/docs/azure/quick-start/install/cli.mdx b/docs/azure/quick-start/install/cli.mdx
@@ -0,0 +1,40 @@
+---
+hide_title: true
+sidebar_label: CLI Installer
+sidebar_position: 3
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import CommonCloudPrerequisites from "../../../common/partials/common/_prerequisites.mdx";
+import AzureCloudPrerequisites from "../../partials/common/_prerequisites.mdx";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import GitHubPrerequisites from "../../../common/partials/github/_prerequisites.mdx";
+import GitHubClusterCreateCmd from "../../partials/github/_cluster-create.mdx";
+import GitLabPrerequisites from "../../../common/partials/gitlab/_prerequisites.mdx";
+import GitLabClusterCreateCmd from "../../partials/gitlab/_cluster-create.mdx";
+import CommonTerminalOutput from "../../../common/partials/common/_terminal-output.mdx";
+import GitHubLogo from '../../../common/components/GitHubLogo.jsx'
+import GitLabLogo from '../../../common/components/GitLabLogo.jsx'
+import styles from "../../../stylesheets/tabs.module.css";
+import GitHubHandoffScreen from "../../../img/azure/github/handoff-screen.png";
+import GitLabHandoffScreen from "../../../img/azure/gitlab/handoff-screen.png";
+
+<CommonCloudPrerequisites />
+<AzureCloudPrerequisites />
+
+<Tabs groupId="git_provider" defaultValue="github" queryString>
+
+    <TabItem attributes={{ className: styles.github }} value="github" label={ <GitHubLogo /> }>
+        <GitHubPrerequisites />
+        <GitHubClusterCreateCmd />
+        <CommonTerminalOutput cloud="Azure"  minutes="20" handoffScreen={GitHubHandoffScreen} />
+    </TabItem>
+
+    <TabItem attributes={{ className: styles.gitlab }} value="gitlab" label={ <GitLabLogo /> }>
+        <GitLabPrerequisites />
+        <GitLabClusterCreateCmd />
+        <CommonTerminalOutput cloud="Azure"  minutes="20" handoffScreen={GitLabHandoffScreen} />
+    </TabItem>
+
+</Tabs>
diff --git a/docs/azure/quick-start/repositories.mdx b/docs/azure/quick-start/repositories.mdx
@@ -0,0 +1,10 @@
+---
+title: Repositories
+sidebar_position: 3
+description: the git repositories created by the kubefirst platform
+image: "https://kubefirst.konstruct.io/docs/img/kubefirst.svg"
+---
+
+import REPOSITORES from "../../common/repositories.mdx";
+
+<REPOSITORES />