Merge branch 'main' into gcp-docs

.github/workflows/check-links.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@master
 
       - name: Validate Links Markdown ${{ matrix.file-extension }} files
-        if: success() || failure()
+        if: always()
         uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
           config-file: '.markdownlinkcheck.json'

.github/workflows/check-markdown.yml

@@ -1,19 +1,34 @@
+---
 name: Markdown Syntax Validation
 
 on: [push, workflow_dispatch]
 
 jobs:
   markdown-check:
+    strategy:
+      matrix:
+        configs: [
+          {
+            which: ".md",
+            files: "**.md",
+            config: "md.markdownlint.json"
+          },
+          {
+            which: ".mdx",
+            files: "**.mdx",
+            config: "mdx.markdownlint.json"
+          }
+        ]
+
     runs-on: ubuntu-latest
     steps:
       - name: Checkout this repository
         uses: actions/checkout@main
 
-      - name: Validate Markdown
+      - name: Validate Markdown (${{ matrix.configs.which }})
         uses: DavidAnson/[email protected]
         with:
-            command: config
-            globs: |
-              .markdownlint.json
-              **.md
-              **.mdx
+          command: config
+          globs: |
+            ${{ matrix.configs.config }}
+            ${{ matrix.configs.files }}

.github/workflows/check-signed.yml

@@ -2,7 +2,7 @@ name: Check signed commits
 on: pull_request
 
 jobs:
-  build:
+  signed-commits-check:
     name: Validate if commits in PR are signed 
     runs-on: ubuntu-latest
     steps:

.github/workflows/publish.yaml

@@ -1,16 +1,25 @@
+---
 name: Release new docs
+
 env:
   ARGO_NAMESPACE: argo
   ARGO_VERSION: v3.4.1
   CONTAINER_REGISTRY_URL: 'public.ecr.aws/kubefirst'
+
+concurrency: ci-release-docs
+
 on:
   push:
     branches:
       - main
+    paths-ignore:
+      - '.github/**'
+      - '.tools/**'
   workflow_dispatch:
 
 jobs:
   release:
+    if: ${{ github.actor != 'kube1st' }}
     runs-on: self-hosted
     steps:
       - name: Setup Runner for Argo
@@ -38,7 +47,7 @@ jobs:
       - name: Temporarily disable docs branch protections
         uses: benjefferies/branch-protection-bot@master
         with:
-          access_token: ${{ secrets.ACCESS_TOKEN }}
+          access_token: ${{ secrets.DOCS_PERMISSIONS_TOKEN }}
           branch: ${{ github.event.repository.default_branch }}
 
       # todo need to look repositoryGitURL, this needs to be overrideable from here and respected on the template side for both repositories
@@ -61,5 +70,5 @@ jobs:
         uses: benjefferies/branch-protection-bot@master
         if: always()  # Force to always run this step to ensure the protection is always turned back on no matetr if previous step fail
         with:
-          access_token: ${{ secrets.ACCESS_TOKEN }}
+          access_token: ${{ secrets.DOCS_PERMISSIONS_TOKEN }}
           branch: ${{ github.event.repository.default_branch }}

.vale.ini

@@ -8,3 +8,6 @@ mdx = md
 BasedOnStyles = Custom
 Packages = alex
 IgnoredScopes = code
+BlockIgnores = (?s) *(import.*?\n), \
+               (?s) *(### gitops\n)
+TokenIgnores = (?s) *(export.*?\n)

CONTRIBUTING.md

@@ -13,7 +13,7 @@ _For contribution to the kubefirst CLI, please refer yourself to the [CONTRIBUTI
   - [Markdown](#markdown)
   - [Search Index](#search-index)
   - [Testing](#testing)
-  - [Update docs accross versions](#update-docs-accross-versions)
+  - [Update docs across versions](#update-docs-across-versions)
   - [Versioning](#versioning)
 - [Help](#help)
 
@@ -81,6 +81,32 @@ We also enforce some styling to prevent ambiguity, and ensure consistency for:
 - MD049: underscores for italic text.
 - MD050: asterisks for bold text.
 
+### Markdown React
+
+We are also using MDX files, which bring some advantages, and maintenance complications.
+
+#### Advantages
+
+We can now use React syntax to simplify repetition of sections: as one example, check [docs/civo/overview.mdx](./docs/civo/overview.mdx) where we use `<CommonProvisionProcess firstitem="Create a Kubernetes cluster in the Civo cloud."/>` in the file to display the common provision process which is nearly the same for each cloud. To be able to use this component, we imported the file with the line of code `import CommonProvisionProcess from "@site/docs/common/partials/common/_provision-process.mdx";'` at the top. You can also send pass objects, see them as variables, to customize the imported component. In this case, each provision process is the same except the first item, which is specific to the cloud selected.
+
+It is important that partial filenames start with an underscore like `_provision-process.mdx`, so Docusaurus does not generate a separate documentation page for them.
+
+#### Complications
+
+The minimizing of content duplication is making the content easier to maintain, and at the same time, way more complicated with all the import statements, and non-basic Markdown code. It means managing a lot more files, and often editing more than one file for a specific section or a specific rendered page of the documentation.
+
+##### MDX v1 vs v2 support
+
+MDX v2 will be supported in Docusaurus v3, which is not available yet, so this brings other complications.
+
+###### React Comments
+
+HTML style comments `<!-- this is a comment -->` in MDX v1 were replaced by `{/* this is a comment */}` in MDX v2. Since GitHub is using syntax highlight from MDX v2, the latest display well in GitHub, but isn't supported yet in Docusaurus as its using MDX v1. It means that the HTML comments will be displayed as if the code was removed if you check the file diff in the GitHub web interface. Until Docusaurus v2 is released, the fix is simple: instead of commenting directly in the `.mdx`` files for issues or todos, please create GitHub issues for what need to be done. Even when Docusaurus will support MDX v2 like GitHub, it's best practice not to comment directly tasks or todos in the file, but to create GitHub issues anyway.
+
+###### Component props variables
+
+In MDX v1, JSX and Markdown don't interoperate well: it has been fixed in MDX v2. It means that if you pass a variable as you saw in the `CommonProvisionProcess` example shown above, if you use `{props.firstitem}` in the imported `.mdx` file, it will be treated as text. The fix is to enclose the variable between HTML tags so it's treated as JSX. It could be as sample as putting it between span `<span>{props.firstitem}</span>` like we did in [docs/common/partials/common/_provision-process.mdx](./docs/common/partials/common/_provision-process.mdx).
+
 #### Special Syntax
 
 If you want to create tabs, it will possible, thanks to the [remark-docusaurus-tabs plugin](https://github.com/mccleanp/remark-docusaurus-tabs). You can do it by using the following syntax:
@@ -147,7 +173,7 @@ To run our documentation locally, simply run `npm start`.
 
 > If you modify the CSS, the changes aren't picked up by the development server like when you modify the documentation content. You need to restart the server with npm.
 
-### Update docs accross versions
+### Update docs across versions
 
 Sometimes changes in `v.next` are also valid for previous versions, which is often the case when refactoring a section, or adding missing information to a page. You can either copy the change content manually, or use the ZSH tools we created easily for that. First, you need to stage the file(s) you modified or created. Once it's done, run this command from the documentation folder in your terminal:
 

README.md

@@ -2,7 +2,6 @@
 
 Welcome to the open source repository that powers [docs.kubefirst.io](https://docs.kubefirst.io)
 
-# Contributing
+## Contributing
 
 We welcome fixes and improvements to our documentation. Our contributors guide is available at [CONTRIBUTING.md](./CONTRIBUTING.md).
-

charts/docs/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
-appVersion: 533ba6f
+appVersion: 8e33a52
 description: Kubefirst documentation Helm chart
 name: docs
 type: application
-version: 0.25.0
+version: 0.43.0

docs/aws/advanced/certificates.mdx

@@ -24,6 +24,6 @@ On local versions of the kubefirst platform, we leverage [mkcert](https://github
 
 To trust mkcerts in your browser, run
 
-```bash
+```shell
 mkcert -install
 ```

docs/aws/advanced/install.mdx

@@ -28,9 +28,9 @@ import GitHubInstall from '@site/docs/aws/partials/github/_install.mdx'
 import GitLabInstall from '@site/docs/aws/partials/gitlab/_install.mdx'
 
 <Tabs groupId="git_provider" defaultValue="github" queryString>
-    <TabItem 
+    <TabItem
       attributes={{className: styles.github}}
-      value="github" 
+      value="github"
       label={
         <div className="git-tab">
           <img src="https://assets.kubefirst.com/console/github.svg" />
@@ -40,7 +40,7 @@ import GitLabInstall from '@site/docs/aws/partials/gitlab/_install.mdx'
     >
       <GitHubInstall />
     </TabItem>
-    <TabItem 
+    <TabItem
       value="gitlab"
       attributes={{className: styles.gitlab}}
       label={

docs/aws/explore/user-creation.mdx

@@ -13,7 +13,7 @@ import GitLabUserCreation from '@site/docs/civo/partials/gitlab/_user-creation.m
     <TabItem value="github" label="GitHub" attributes={{className: styles.github}}>
       <GitHubUserCreation />
     </TabItem>
-    <TabItem value="gitlab" label="GitLab" attributes={{className: styles.gitlab}}> 
+    <TabItem value="gitlab" label="GitLab" attributes={{className: styles.gitlab}}>
       <GitLabUserCreation />
     </TabItem>
-</Tabs>
+</Tabs>

docs/aws/overview.mdx

@@ -12,6 +12,7 @@ import TabItem from "@theme/TabItem";
 import styles from "@site/docs/stylesheets/tabs.module.css";
 import ReactDom from 'react-dom'
 import * as config from "@site/docs/constants.js"
+import CommonProvisionProcess from "@site/docs/common/partials/common/_provision-process.mdx";
 
 <div
   style={{
@@ -30,26 +31,17 @@ import GitLabOverview from '@site/docs/aws/partials/gitlab/_overview.mdx'
 
 # Overview
 
-The aws provisioning process will:
-- create a vpc, subnets, iam, and eks cluster in your specified aws account
-<!-- details below this line apply everywhere -->
-- create a gitops git repository from our gitops-template, customized for you, and store it in your git provider
-- install argocd and register it with your gitops repo so that your main branch powers the platform
-- install all the platform apps using argocd gitops preconfigured sync waves (gitops repo `/registry` folder)
-- apply terraform to configure Vault (gitops repo `/terraform/vault` folder)
-- bind a webhook to atlantis to automate terraform executions
-- integrate argo workflows with your git provider
-- install argo workflow automation to build containers, publish charts, and provide gitops delivery pipelines
-- install a sample app git repository that uses this automation to demonstrate gitops app delivery and promotion (metaphor repo)
+The AWS provisioning process will:
+<CommonProvisionProcess firstitem="Create a Kubernetes cluster in the AWS cloud."/>
 
 ![kubefirst AWS with GitHub Cluster Diagram](../img/aws/github/installation-diagram-light.png#light-mode)![kubefirst AWS with GitHub Cluster Diagram](../img/aws/github/installation-diagram-dark.png#dark-mode)
 
 # Applications
 
 <Tabs groupId="git_provider" defaultValue="github" queryString>
-    <TabItem 
+    <TabItem
       attributes={{className: styles.github}}
-      value="github" 
+      value="github"
       label={
         <div className="git-tab">
           <img src="https://assets.kubefirst.com/console/github.svg" />
@@ -59,7 +51,7 @@ The aws provisioning process will:
     >
       <GitHubOverview />
     </TabItem>
-    <TabItem 
+    <TabItem
       value="gitlab"
       attributes={{className: styles.gitlab}}
       label={

docs/aws/partials/common/_cluster-connectivity.mdx

@@ -2,12 +2,12 @@
 
 To connect to your new Kubernetes cluster, run
 
-```bash
+```shell
 export KUBECONFIG=~/.k1/kubeconfig
 ```
 
 To view all cluster pods, run
 
-```bash
+```shell
 kubectl get pods -A
 ```

docs/aws/partials/common/_prerequisites.mdx

@@ -22,4 +22,4 @@ There are other ways to install kubefirst for different operating systems, archi
 1. Create an AWS account with billing enabled.
 2. Establish a public hosted zone with DNS routing established ([docs](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)).
 3. Connect with [Administrator Access](https://console.aws.amazon.com/iam/home?#/policies/arn:aws:iam::aws:policy/AdministratorAccessserviceLevelSummary) IAM credentials to your AWS account ([docs](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)).
-4. Our Homebrew package will automatically install the [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) dependency. If you use another installation method, you will need to install this utility.
+4. Our Homebrew package will automatically install the [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) dependency. If you use another installation method, you will need to install this utility.

docs/aws/partials/common/_root-credentials-cmd.mdx

@@ -2,7 +2,7 @@
 
 To obtain your 3 initial passwords, run
 
-```bash
+```shell
 kubefirst aws root-credentials
 ```
 

docs/aws/partials/github/_install.mdx

@@ -50,7 +50,7 @@ kubefirst aws create \
 
 To obtain your 3 initial passwords, run
 
-```bash
+```shell
 kubefirst aws root-credentials
 ```
 
@@ -60,12 +60,12 @@ kubefirst aws root-credentials
 
 Replace `kubefirst` in the command below with your cluster's name if you specified one
 
-```bash
+```shell
 aws eks update-kubeconfig --name kubefirst
 ```
 
 To view all cluster pods run
 
-```bash
+```shell
 kubectl get pods -A
-```
+```

docs/aws/partials/github/_repositories.mdx

@@ -43,4 +43,4 @@ That was just GitHub. Take a look at all the Terraform providers that are availa
 
 To make infrastructure and configuration changes with Terraform, simply open a pull request against any of the Terraform directory folders in the `gitops` repository. Your pull request will automatically provide plans, state locks, and applies, and even comment in the merge request itself. You'll have a simple, peer reviewable, auditable changelog of all infrastructure and configuration changes.
 
-![Atlantis GitHub](../../../img/common/github/atlantis.png)
+![Atlantis GitHub](../../../img/common/github/atlantis.png)

docs/aws/partials/gitlab/_install.mdx

@@ -26,7 +26,7 @@ It installs a fully automated platform of open source cloud native tools with a
 
 ### Step 1 - Create your kbot user and a personal access token
 
-The kubefirst cli will automatically create one admin user for you named `kbot`. After the installation, you will temporarily use that `kbot` account to onboard yourself and the rest your team to the platform. From that point forward, the `kbot` should only be used for automated activities, and you should use your own personal account.
+The kubefirst CLI will automatically create one admin user for you named `kbot`. After the installation, you will temporarily use that `kbot` account to onboard yourself and the rest your team to the platform. From that point forward, the `kbot` should only be used for automated activities, and you should use your own personal account.
 
 The `kbot` user needs to be associated with a GitLab user account that can be used as your organization's bot account. Log out of GitLab and create a new GitLab account to represent this new `kbot` account. Because this account will be used for automation, it's a good to choose a username that generically represents your company or project name. You can also have fun with it and give your bot a fun name - the point is that this is not an account for your long term personal use, it's for the kubefirst platform system to use.
 
@@ -54,7 +54,7 @@ kubefirst aws create \
 
 To obtain your 3 initial passwords, run
 
-```bash
+```shell
 kubefirst aws root-credentials
 ```
 
@@ -64,12 +64,12 @@ kubefirst aws root-credentials
 
 Replace `kubefirst` in the command below with your cluster's name if you specified one
 
-```bash
+```shell
 aws eks update-kubeconfig --name kubefirst
 ```
 
 To view all cluster pods run
 
-```bash
+```shell
 kubectl get pods -A
-```
+```

docs/aws/quick-start/iac-and-app-delivery.mdx

@@ -9,7 +9,7 @@ image: "https://docs.kubefirst.io/img/logo.svg"
 
 ## Step 1: Console UI
 
-Once the aws platform has completed provisioning, the Console UI will provide you with a dashboard to navigate to some of the new services that were provisioned.
+Once the AWS platform has completed provisioning, the Console UI will provide you with a dashboard to navigate to some of the new services that were provisioned.
 
 ![console UI](../../img/common/github/console.png)
 
@@ -31,6 +31,6 @@ The metaphor pipeline will:
 - the release stage of the pipeline will republish the chart, this time without the release candidate notation making it an officially released version and prepare the metaphor application chart for the next release version.
 - the officially released chart will be set as the desired Helm chart for production.
 
-To watch this pipeline occur, make any change to the `main` branch of the `metaphor` repository. If you're not feeling creative, you can just add a newline to the README.md. Once a file in `main` is changed, navigate to metaphor's CI/CD in the GitHub Actions tab to see the workflows get submitted to Argo workflows.
+To watch this pipeline occur, make any change to the `main` branch of the `metaphor` repository. If you're not feeling creative, you can just add a newline to the README.md. Once a file in `main` is changed, navigate to metaphor's CI/CD in the GitHub Actions tab to see the workflows get submitted to Argo Workflows.
 
 You can visit the metaphor development, staging, and production apps in your browser to see the versions change and Argo CD syncs the apps. The metaphor URLs can be found in your GitOps and metaphor project `README.md` files.

docs/aws/quick-start/install/cli.mdx

@@ -42,7 +42,7 @@ export const TabLabel = ({ imgSrc, label }) => (
   <GitHubClusterCreateCmd />
 
   <CommonTerminalOutput />
-  
+
   <AWSRootCredentialsCmd />
 
   <CommonClusterConnectivity />