From 619ccafc7f833afbd908c0b48fbe39a824657939 Mon Sep 17 00:00:00 2001 From: Soule BA Date: Tue, 12 Sep 2023 16:30:16 +0200 Subject: [PATCH 1/9] Create mpas section If implemented this will add a mpas section that explains how to install and get started with mpas. Signed-off-by: Soule BA --- content/en/mpas/core_concepts.md | 11 + content/en/mpas/getting_started.md | 334 +++++++++++++++++++++++ content/en/mpas/overview/_index.md | 10 + content/en/mpas/overview/bootstrap.md | 13 + content/en/mpas/overview/installation.md | 25 ++ 5 files changed, 393 insertions(+) create mode 100644 content/en/mpas/core_concepts.md create mode 100644 content/en/mpas/getting_started.md create mode 100644 content/en/mpas/overview/_index.md create mode 100644 content/en/mpas/overview/bootstrap.md create mode 100644 content/en/mpas/overview/installation.md diff --git a/content/en/mpas/core_concepts.md b/content/en/mpas/core_concepts.md new file mode 100644 index 00000000..192edab8 --- /dev/null +++ b/content/en/mpas/core_concepts.md @@ -0,0 +1,11 @@ +--- +title: "Core Concepts" +description: Core Concepts of Mpas. +lead: "" +date: 2023-09-12T10:37:58+01:00 +lastmod: 2023-09-12T10:37:58+01:00 +draft: true +images: [] +weight: 101 +toc: true +--- diff --git a/content/en/mpas/getting_started.md b/content/en/mpas/getting_started.md new file mode 100644 index 00000000..b3ace43d --- /dev/null +++ b/content/en/mpas/getting_started.md @@ -0,0 +1,334 @@ +--- +title: "Get Started with Mpas" +description: "" +lead: "" +date: 2023-09-12T10:37:58+01:00 +lastmod: 2023-09-12T10:37:58+01:00 +draft: true +images: [] +weight: 101 +toc: true +--- + +This tutorial shows you how to bootstrap Mpas to a Kubernetes cluster and deploy +a simple application. + +## Prerequisites + +- A Kubernetes cluster +- A Github access token with `repo` scope +- kubectl + +## Objectives + +- Bootstrap Mpas to a Kubernetes cluster +- Deploy a simple application + +## Install the Mpas CLI + +The Mpas CLI is the primary tool for interacting with Mpas. It can be used to +bootstrap Mpas to a Kubernetes cluster. + +To install the Mpas CLI using `brew`: + +```bash +brew install open-component-model/tap/mpas +``` + +For other installation methods, see the [installation guide](/mpas/overview/installation/). + +## Bootstrap Mpas + +### Export your Github access token + +The Mpas CLI uses your Github access token to authenticate with Github. To create a +Github access token, see the [Github documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). + +```bash +export GITHUB_TOKEN= +export GITHUB_USER= +``` + +### Bootstrap Mpas + +To bootstrap Mpas to your Kubernetes cluster, run the following command: + +```bash +mpas bootstrap github \ + --owner=$GITHUB_USER \ + --repository=mpas-bootstrap \ + --path=./clusters/my-cluster \ + --dev \ + --personal +``` + +This command will create a new Github repository called `mpas-bootstrap` and bootstrap +Mpas to your Kubernetes cluster. The following components will be installed: +- [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will + install and manage the other components. +- [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator + that enable the automated deployment of software using the Open Component Model and Flux. +- [Git-controller](https://github.com/open-component-model/git-controller): A + Kubernetes controller that will create Pull Requests in the target Github repository + when changes are made to the cluster. +- [Replication-controller](https://github.com/open-component-model/git-controller): +- [Mpas-product-controller](https://github.com/open-component-model/mpas-product-controller): +- [Mpas-project-controller](https://github.com/open-component-model/mpas-project-controller): + +The output is similar to the following: + +```bash +Running mpas bootstrap ... + ✓ Preparing Management repository mpas-bootstrap + ✓ Fetching bootstrap component from ghcr.io/open-component-model/mpas-bootstrap-component + ✓ Installing flux with version v2.1.0 + ✓ Generating git-controller manifest with version v0.7.1 + ✓ Generating mpas-product-controller manifest with version v0.3.3 + ✓ Generating mpas-project-controller manifest with version v0.1.2 + ✓ Generating ocm-controller manifest with version v0.12.2 + ✓ Generating replication-controller manifest with version v0.6.2 + ✓ Waiting for components to be ready + +Bootstrap completed successfully! +``` + +After completing the bootstrap process, the target github repository will contain +yaml manifests for the components to be installed on the cluster. The cluster will +also have the components installed. Furthermore the installed `Flux` components will +be configured to watch the target github repository for changes in the path `./clusters/my-cluster`. + +#### Clone the git repository + +Clone the `mpas-bootstrap` repository to your local machine: + +```sh +git clone https://github.com/$GITHUB_USER/mpas-bootstrap +cd mpas-bootstrap +``` + +#### Registry certificate + +The `--dev` flag will bootstrap Mpas in development mode, which means that a self-signed +certificate will be used for the Mpas components to communicate with the internal `oci` registry. + +You may want to provide your own certificate for production use, for example by using [cert-manager](https://cert-manager.io/docs/usage/certificate/). +The certificate should be named `ocm-registry-tls-certs` and should be placed in the `mpas-system` +and `ocm-system` namespaces. You can use [syncing-secrets-across-namespaces](https://cert-manager.io/docs/tutorials/syncing-secrets-across-namespaces/) guide to sync the certificate between namespaces. + + +### Deploy podinfo application + +The [podinfo application](https://github.com/stefanprodan/podinfo) has been packaged +as an ocm component and can be retrieved from [Github](ghcr.io/open-component-model/podinfo). + + + +1. Create a secret containing your Github credentials that will be used by Mpas to +create your project repository. + +```bash +kubectl create secret generic \ + github-access \ + --from-literal=username=$GITHUB_USER \ + --from-literal=password=$GITHUB_TOKEN \ + -n mpas-system +``` + +2. Create a project that will contain the podinfo application. + +Let's create a directory for the project: + +```bash +mkdir -p ./clusters/my-cluster/podinfo +```` + +Then, create a `project.yaml` file in the `./clusters/my-cluster/podinfo` directory: + +```bash +cat <> ./clusters/my-cluster/podinfo/project.yaml +apiVersion: mpas.ocm.software/v1alpha1 +kind: Project +metadata: + name: podinfo-application + namespace: mpas-system +spec: + flux: + interval: 1h + git: + provider: github + owner: $GITHUB_USER + isOrganization: false + visibility: public + maintainers: + - $GITHUB_USER + existingRepositoryPolicy: adopt + defaultBranch: main + credentials: + secretRef: + name: github-access + commitTemplate: + email: mpas@mpas.ocm.software + message: Initializing Project repository + name: mpas-admin + prune: true +EOF +``` + +Then, apply the project to the clustern in a gitOps fashion: + +```bash +git add --all && git commit -m "Add podinfo project" && git push +``` + +`Flux` will detect the changes and apply the project to the cluster. + +This will create in the cluster a `namespace` for the project, a `service account`, and RBAC. +It will also create a GitHub repository for the project, and configure `Flux` to manage the project's resources. + +3. Clone the project repository + +```bash +git clone https://github.com/$GITHUB_USER/mpas-podinfo-application +cd mpas-podinfo-application +``` + +4. Add the podinfo component subscription + +we need a secret in the project namespace that will be used to retrieve the component from the registry: + +```bash +kubectl create secret generic \ + github-access \ + --from-literal=username=$GITHUB_USER \ + --from-literal=password=$GITHUB_TOKEN \ + -n mpas-podinfo-application +``` + +**Note** The credentials shall have access to github packages. + +```bash +cat <> ./subscriptions/podinfo.yaml +apiVersion: delivery.ocm.software/v1alpha1 +kind: ComponentSubscription +metadata: + name: podinfo-subscription + namespace: mpas-podinfo-application +spec: + interval: 30s + component: mpas.ocm.software/podinfo + semver: ">=v1.0.0" + source: + url: ghcr.io/open-component-model/mpas + secretRef: + name: github-access + destination: + url: ghcr.io/$GITHUB_USER + secretRef: + name: github-access +EOF +``` + +Then, apply the `ComponentSubscription` to the project in a gitOps fashion: + +```bash +git add --all && git commit -m "Add podinfo subscription" && git push +``` + +`Flux` will detect the changes and apply the subscription to the cluster. + +This will replicate the product referenced by the `ComponentSubscription` `spec.component` field from +defined registry in the `spec.source.url` to the `spec.destination.url` registry. + +5. Add a target for the podinfo application + +The target will define where the application will be installed + +```bash +cat <> ./targets/podinfo.yaml +apiVersion: mpas.ocm.software/v1alpha1 +kind: Target +metadata: + name: podinfo-kubernetes-target + namespace: mpas-podinfo-application + labels: + target.mpas.ocm.software/ingress-enabled: "true" # DO NOT CHANGE. expected by the component for target selection. +spec: + type: kubernetes + access: + targetNamespace: podinfo +EOF +``` + +Then, apply the `Target` to the project in a gitOps fashion: + +```bash +git add --all && git commit -m "Add a target for podinfo" && git push +``` + +`Flux` will detect the changes and apply the target to the cluster. + +6. Deploy the podinfo application + +In order to deploy the podinfo application, we need to create a `ProductDeploymentGenerator` resource: + +```bash +cat <> ./generators/podinfo.yaml +apiVersion: mpas.ocm.software/v1alpha1 +kind: ProductDeploymentGenerator +metadata: + name: podinfo + namespace: mpas-podinfo-application +spec: + interval: 1m + serviceAccountName: mpas-podinfo-application + subscriptionRef: + name: podinfo-subscription + namespace: mpas-podinfo-application +EOF +``` + +As part of step 2, a `service account` was created for the project. We will use this service account +to provide the necessary permissions to the `ProductDeploymentGenerator` to pull +the podinfo component from the registry. + +First create a secret containing the credentials for the service account: + +```bash +kubectl create secret docker-registry github-registry-key --docker-server=ghcr.io \ + --docker-username=$GITHUB_USER --docker-password=$GITHUB_TOKEN \ + --docker-email= -n mpas-podinfo-application +``` + +Then, patch the service account to use the secret: + +```bash +kubectl patch serviceaccount mpas-podinfo-application -p '{"imagePullSecrets": [{"name": "github-registry-key"}]}' \ + -n mpas-podinfo-application +``` + +Then, apply the `ProductDeploymentGenerator` to the project in a gitOps fashion: + +```bash +git add --all && git commit -m "Add podinfo deployment generator" && git push +``` + +`Flux` will detect the changes and apply the resource to the cluster. + +This will create a pull request in the project repository with the `ProductDeployment` resource +that will deploy the podinfo application. + + + +Go to the project repository and retrieve the pull request. +It should contains a `ProductDeployment` declaration that provides the configuration and +all steps needed to deploy the product, as well as a `values.yaml` file. The `values` file +contains values that should used to configure the different resources that are part of +the product to be deployed. There is a check that should pass before merging the pull request. + +Once the pull request is merged, `Flux` will detect the changes and deploy the application to the cluster. diff --git a/content/en/mpas/overview/_index.md b/content/en/mpas/overview/_index.md new file mode 100644 index 00000000..9689731d --- /dev/null +++ b/content/en/mpas/overview/_index.md @@ -0,0 +1,10 @@ +--- +title : "Overview" +description: "Overview of OCM." +weight: 1 +lead: "" +date: 2023-09-12T10:37:58+01:00 +lastmod: 2023-09-12T10:37:58+01:00 +draft: true +images: [] +--- diff --git a/content/en/mpas/overview/bootstrap.md b/content/en/mpas/overview/bootstrap.md new file mode 100644 index 00000000..43d35892 --- /dev/null +++ b/content/en/mpas/overview/bootstrap.md @@ -0,0 +1,13 @@ +--- +title: "Bootstrap" +description: "" +lead: "" +date: 2023-09-12T10:37:58+01:00 +lastmod: 2023-09-12T10:37:58+01:00 +draft: true +images: [] +weight: 101 +toc: true +--- + + diff --git a/content/en/mpas/overview/installation.md b/content/en/mpas/overview/installation.md new file mode 100644 index 00000000..799b78f8 --- /dev/null +++ b/content/en/mpas/overview/installation.md @@ -0,0 +1,25 @@ +--- +title: "Installation" +description: "" +lead: "" +date: 2023-09-12T10:37:58+01:00 +lastmod: 2023-09-12T10:37:58+01:00 +draft: true +images: [] +weight: 101 +toc: true +--- + +## Homebrew + +To install the OCM CLI you can download binaries for major platforms from the GitHub [releases page](https://github.com/open-component-model/mpas/releases). + +You can also install via [homebrew](https://brew.sh/) for macOS and Linux: + +`brew install open-component-model/tap/mpas` + +## Bash + +To install with `bash` for macOS or Linux execute the following command: + +`curl -sfL https://raw.githubusercontent.com/open-component-model/mpas/main/install.sh | sh -` From 0ba4c31923096d4cd77f9c9553998a42f0f64314 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Tue, 19 Sep 2023 17:10:33 +0200 Subject: [PATCH 2/9] minor changes --- content/en/mpas/getting_started.md | 34 ++++++++++++------------ content/en/mpas/overview/installation.md | 5 ++-- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/content/en/mpas/getting_started.md b/content/en/mpas/getting_started.md index b3ace43d..fdc97cc2 100644 --- a/content/en/mpas/getting_started.md +++ b/content/en/mpas/getting_started.md @@ -1,5 +1,5 @@ --- -title: "Get Started with Mpas" +title: "Get Started with MPAS" description: "" lead: "" date: 2023-09-12T10:37:58+01:00 @@ -10,7 +10,7 @@ weight: 101 toc: true --- -This tutorial shows you how to bootstrap Mpas to a Kubernetes cluster and deploy +This tutorial shows you how to bootstrap MPAS to a Kubernetes cluster and deploy a simple application. ## Prerequisites @@ -21,15 +21,15 @@ a simple application. ## Objectives -- Bootstrap Mpas to a Kubernetes cluster +- Bootstrap MPAS to a Kubernetes cluster - Deploy a simple application -## Install the Mpas CLI +## Install the MPAS CLI -The Mpas CLI is the primary tool for interacting with Mpas. It can be used to -bootstrap Mpas to a Kubernetes cluster. +The MPAS CLI is the primary tool for interacting with MPAS. It can be used to +bootstrap MPAS to a Kubernetes cluster. -To install the Mpas CLI using `brew`: +To install the MPAS CLI using `brew`: ```bash brew install open-component-model/tap/mpas @@ -37,11 +37,11 @@ brew install open-component-model/tap/mpas For other installation methods, see the [installation guide](/mpas/overview/installation/). -## Bootstrap Mpas +## Bootstrap MPAS ### Export your Github access token -The Mpas CLI uses your Github access token to authenticate with Github. To create a +The MPAS CLI uses your Github access token to authenticate with Github. To create a Github access token, see the [Github documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). ```bash @@ -49,9 +49,9 @@ export GITHUB_TOKEN= export GITHUB_USER= ``` -### Bootstrap Mpas +### Bootstrap MPAS -To bootstrap Mpas to your Kubernetes cluster, run the following command: +To bootstrap MPAS to your Kubernetes cluster, run the following command. If nothing is specified it will use the KUBECONFIG specified in the user's environment. It is also possible to specify a dedicated config using the --kubeconfig option. ```bash mpas bootstrap github \ @@ -63,7 +63,7 @@ mpas bootstrap github \ ``` This command will create a new Github repository called `mpas-bootstrap` and bootstrap -Mpas to your Kubernetes cluster. The following components will be installed: +MPAS to your Kubernetes cluster. The following components will be installed: - [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will install and manage the other components. - [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator @@ -72,8 +72,8 @@ Mpas to your Kubernetes cluster. The following components will be installed: Kubernetes controller that will create Pull Requests in the target Github repository when changes are made to the cluster. - [Replication-controller](https://github.com/open-component-model/git-controller): -- [Mpas-product-controller](https://github.com/open-component-model/mpas-product-controller): -- [Mpas-project-controller](https://github.com/open-component-model/mpas-project-controller): +- [MPAS-product-controller](https://github.com/open-component-model/mpas-product-controller): +- [MPAS-project-controller](https://github.com/open-component-model/mpas-project-controller): The output is similar to the following: @@ -108,8 +108,8 @@ cd mpas-bootstrap #### Registry certificate -The `--dev` flag will bootstrap Mpas in development mode, which means that a self-signed -certificate will be used for the Mpas components to communicate with the internal `oci` registry. +The `--dev` flag will bootstrap MPAS in development mode, which means that a self-signed +certificate will be used for the MPAS components to communicate with the internal `oci` registry. You may want to provide your own certificate for production use, for example by using [cert-manager](https://cert-manager.io/docs/usage/certificate/). The certificate should be named `ocm-registry-tls-certs` and should be placed in the `mpas-system` @@ -129,7 +129,7 @@ mpas create project podinfo-project --export > podinfo-project.yaml We should also have a command to create a component subscription as well as a product deployment generator. ---> -1. Create a secret containing your Github credentials that will be used by Mpas to +1. Create a secret containing your Github credentials that will be used by MPAS to create your project repository. ```bash diff --git a/content/en/mpas/overview/installation.md b/content/en/mpas/overview/installation.md index 799b78f8..4b876c18 100644 --- a/content/en/mpas/overview/installation.md +++ b/content/en/mpas/overview/installation.md @@ -10,9 +10,10 @@ weight: 101 toc: true --- -## Homebrew +## Install using Binaries -To install the OCM CLI you can download binaries for major platforms from the GitHub [releases page](https://github.com/open-component-model/mpas/releases). +To install the MPAS CLI you can download binaries for major platforms from the GitHub [releases page](https://github.com/open-component-model/mpas/releases). +## Homebrew You can also install via [homebrew](https://brew.sh/) for macOS and Linux: From 7f83749a24faaef352ddaac956ade112a1ab6017 Mon Sep 17 00:00:00 2001 From: Soule BA Date: Wed, 20 Sep 2023 12:03:13 +0200 Subject: [PATCH 3/9] competing getting started Signed-off-by: Soule BA --- content/en/mpas/getting_started.md | 136 +++++++++++++++++++++-------- 1 file changed, 98 insertions(+), 38 deletions(-) diff --git a/content/en/mpas/getting_started.md b/content/en/mpas/getting_started.md index fdc97cc2..7c5b57d0 100644 --- a/content/en/mpas/getting_started.md +++ b/content/en/mpas/getting_started.md @@ -16,7 +16,7 @@ a simple application. ## Prerequisites - A Kubernetes cluster -- A Github access token with `repo` scope +- A GitHub access token with `repo` scope - kubectl ## Objectives @@ -39,10 +39,10 @@ For other installation methods, see the [installation guide](/mpas/overview/inst ## Bootstrap MPAS -### Export your Github access token +### Export your GitHub access token -The MPAS CLI uses your Github access token to authenticate with Github. To create a -Github access token, see the [Github documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). +The MPAS CLI uses your GitHub access token to authenticate with GitHub. To create a +GitHub access token, see the [GitHub documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token). ```bash export GITHUB_TOKEN= @@ -67,7 +67,7 @@ MPAS to your Kubernetes cluster. The following components will be installed: - [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will install and manage the other components. - [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator - that enable the automated deployment of software using the Open Component Model and Flux. + that enable the automated deployment of software using the Open Component Model and `Flux``. - [Git-controller](https://github.com/open-component-model/git-controller): A Kubernetes controller that will create Pull Requests in the target Github repository when changes are made to the cluster. @@ -121,6 +121,19 @@ and `ocm-system` namespaces. You can use [syncing-secrets-across-namespaces](htt The [podinfo application](https://github.com/stefanprodan/podinfo) has been packaged as an ocm component and can be retrieved from [Github](ghcr.io/open-component-model/podinfo). + + -1. Create a secret containing your Github credentials that will be used by MPAS to +1. Create a secret containing your GitHub credentials that will be used by MPAS to create your project repository. ```bash @@ -173,7 +186,7 @@ spec: secretRef: name: github-access commitTemplate: - email: mpas@mpas.ocm.software + email: message: Initializing Project repository name: mpas-admin prune: true @@ -191,16 +204,17 @@ git add --all && git commit -m "Add podinfo project" && git push This will create in the cluster a `namespace` for the project, a `service account`, and RBAC. It will also create a GitHub repository for the project, and configure `Flux` to manage the project's resources. -3. Clone the project repository +3. Add the needed secrets to the namespace + +`Flux` is used to deploy all workloads in a gitOps way. In order for `Flux` to access the internal +registry, we have to provide the certificate to use `https`. ```bash -git clone https://github.com/$GITHUB_USER/mpas-podinfo-application -cd mpas-podinfo-application +kubectl get secret ocm-registry-tls-certs --namespace=mpas-system -o yaml | sed 's/namespace: +.*/namespace: mpas-podinfo-application/' | kubectl apply -f - ``` -4. Add the podinfo component subscription - -we need a secret in the project namespace that will be used to retrieve the component from the registry: +We also need a secret in the project namespace that will be used to communicate with github: ```bash kubectl create secret generic \ @@ -210,7 +224,36 @@ kubectl create secret generic \ -n mpas-podinfo-application ``` -**Note** The credentials shall have access to github packages. +**Note** The credentials should have access to GitHub packages. + +As part of step 2, a `service account` was created for the project. We will use this service account +to provide the necessary permissions to pull from the `ghcr` registry. + +First, create a secret containing the credentials for the service account: + +```bash +kubectl create secret docker-registry github-registry-key --docker-server=ghcr.io \ + --docker-username=$GITHUB_USER --docker-password=$GITHUB_TOKEN \ + --docker-email= -n mpas-podinfo-application +``` + +Then, patch the service account to use the secret: + +```bash +kubectl patch serviceaccount mpas-podinfo-application -p '{"imagePullSecrets": [{"name": "github-registry-key"}]}' \ + -n mpas-podinfo-application +``` + +4. Clone the project repository + +```bash +git clone https://github.com/$GITHUB_USER/mpas-podinfo-application +cd mpas-podinfo-application +``` + +5. Add the podinfo component subscription + +Create a file under `./subscriptions/` that will contains the subscription declaration. ```bash cat <> ./subscriptions/podinfo.yaml @@ -245,10 +288,15 @@ git add --all && git commit -m "Add podinfo subscription" && git push This will replicate the product referenced by the `ComponentSubscription` `spec.component` field from defined registry in the `spec.source.url` to the `spec.destination.url` registry. -5. Add a target for the podinfo application +6. Add a target for the podinfo application The target will define where the application will be installed + + ```bash cat <> ./targets/podinfo.yaml apiVersion: mpas.ocm.software/v1alpha1 @@ -257,7 +305,7 @@ metadata: name: podinfo-kubernetes-target namespace: mpas-podinfo-application labels: - target.mpas.ocm.software/ingress-enabled: "true" # DO NOT CHANGE. expected by the component for target selection. + target.mpas.ocm.software/ingress-enabled: "true" # This label is defined by the component that will use it to select an appropriate target to deploy to. spec: type: kubernetes access: @@ -273,7 +321,7 @@ git add --all && git commit -m "Add a target for podinfo" && git push `Flux` will detect the changes and apply the target to the cluster. -6. Deploy the podinfo application +7. Deploy the podinfo application In order to deploy the podinfo application, we need to create a `ProductDeploymentGenerator` resource: @@ -293,25 +341,6 @@ spec: EOF ``` -As part of step 2, a `service account` was created for the project. We will use this service account -to provide the necessary permissions to the `ProductDeploymentGenerator` to pull -the podinfo component from the registry. - -First create a secret containing the credentials for the service account: - -```bash -kubectl create secret docker-registry github-registry-key --docker-server=ghcr.io \ - --docker-username=$GITHUB_USER --docker-password=$GITHUB_TOKEN \ - --docker-email= -n mpas-podinfo-application -``` - -Then, patch the service account to use the secret: - -```bash -kubectl patch serviceaccount mpas-podinfo-application -p '{"imagePullSecrets": [{"name": "github-registry-key"}]}' \ - -n mpas-podinfo-application -``` - Then, apply the `ProductDeploymentGenerator` to the project in a gitOps fashion: ```bash @@ -326,9 +355,40 @@ that will deploy the podinfo application. Go to the project repository and retrieve the pull request. -It should contains a `ProductDeployment` declaration that provides the configuration and +It should contain a `ProductDeployment` declaration that provides the configuration and all steps needed to deploy the product, as well as a `values.yaml` file. The `values` file -contains values that should used to configure the different resources that are part of +contains values that should be used to configure the different resources that are part of the product to be deployed. There is a check that should pass before merging the pull request. Once the pull request is merged, `Flux` will detect the changes and deploy the application to the cluster. + +After a moment the `ProductDeployment` should be deployed successfully. +It is possible to verify with the command: + +```bash +k describe productDeployment -n mpas-podinfo-application +``` + +The result should something like: + +```bash +Name: podinfo +Namespace: mpas-podinfo-application +Labels: kustomize.toolkit.fluxcd.io/name=mpas-podinfo-application-products + kustomize.toolkit.fluxcd.io/namespace=mpas-system +API Version: mpas.ocm.software/v1alpha1 +Kind: ProductDeployment +Metadata: +... +Status: + Conditions: + Last Transition Time: 2023-09-14T10:14:41Z + Message: Reconciliation success + Observed Generation: 1 + Reason: Succeeded + Status: True + Type: Ready + Observed Generation: 1 +``` + +The application is deployed in the `podinfo` namespace. From de1eca6eeca5a139c495cd2f558efb6335f0d7d2 Mon Sep 17 00:00:00 2001 From: Soule BA Date: Wed, 20 Sep 2023 16:30:44 +0200 Subject: [PATCH 4/9] Add a bootstrap page for MPAS. Signed-off-by: Soule BA --- content/en/mpas/getting_started.md | 13 -- content/en/mpas/overview/bootstrap.md | 167 +++++++++++++++++++++++ content/en/mpas/overview/installation.md | 2 +- 3 files changed, 168 insertions(+), 14 deletions(-) diff --git a/content/en/mpas/getting_started.md b/content/en/mpas/getting_started.md index 7c5b57d0..f31ea843 100644 --- a/content/en/mpas/getting_started.md +++ b/content/en/mpas/getting_started.md @@ -62,19 +62,6 @@ mpas bootstrap github \ --personal ``` -This command will create a new Github repository called `mpas-bootstrap` and bootstrap -MPAS to your Kubernetes cluster. The following components will be installed: -- [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will - install and manage the other components. -- [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator - that enable the automated deployment of software using the Open Component Model and `Flux``. -- [Git-controller](https://github.com/open-component-model/git-controller): A - Kubernetes controller that will create Pull Requests in the target Github repository - when changes are made to the cluster. -- [Replication-controller](https://github.com/open-component-model/git-controller): -- [MPAS-product-controller](https://github.com/open-component-model/mpas-product-controller): -- [MPAS-project-controller](https://github.com/open-component-model/mpas-project-controller): - The output is similar to the following: ```bash diff --git a/content/en/mpas/overview/bootstrap.md b/content/en/mpas/overview/bootstrap.md index 43d35892..c1ffd9e0 100644 --- a/content/en/mpas/overview/bootstrap.md +++ b/content/en/mpas/overview/bootstrap.md @@ -11,3 +11,170 @@ toc: true --- +The `MPAS Bootstrap`` command deploys the following components to your cluster: +- [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will + install and manage the other components. +- [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator + that enable the automated deployment of software using the Open Component Model and `Flux``. +- [Git-controller](https://github.com/open-component-model/git-controller): A + Kubernetes controller that will create Pull Requests in the target Github repository + when changes are made to the cluster. +- [Replication-controller](https://github.com/open-component-model/git-controller): +- [MPAS-product-controller](https://github.com/open-component-model/mpas-product-controller): +- [MPAS-project-controller](https://github.com/open-component-model/mpas-project-controller): + +Besides the above components, the `MPAS Bootstrap` command will also push the corresponding +components manifests to the target Git repository and configure `Flux` to continuously update +the installed components from the target Git repository. + +After the `MPAS Bootstrap` command is executed, the cluster is ready to deploy software +in a gitops fashion using the Open Component Model and `MPAS`. + +{{% alert color="danger" title="Required permissions" %}} +To bootstrap `MPAS`, the person running the command must have **cluster admin rights** for the target Kubernetes cluster. +It is also required that the person running the command to be the **owner** of the GitHub repository, +or to have admin rights of a GitHub organization. +{{% /alert %}} + +## Bootstrap for GitHub + +### GitHub PAT + +For accessing the GitHub API, the boostrap command requires a GitHub personal access token (PAT) +with administration permissions. + +The GitHub PAT can be exported as an environment variable: + +```bash +export GITHUB_TOKEN= +``` + +If the `GITHUB_TOKEN` environment variable is not set, the `MPAS Bootstrap` command will prompt +for the GitHub PAT. + +{{% alert color="danger" title="PAT secret" %}} +Note that the GitHub PAT is stored in the cluster as a **Kubernetes Secret** named `flux-system` +inside the `flux-system` namespace. +{{% /alert %}} + +### Personal account + +Run bootstrap for a repository on your personal GitHub account: + +```bash +mpas bootstrap github \ + --owner= \ + --repository= \ + --path=clusters/my-cluster \ + --dev \ + --personal +``` + +If the specified repository does not exist, the `MPAS Bootstrap` command will create it +as a private repository. If you wish to create a public repository, you can use the `--private=false` +flag. + +### Organization + +If you want to bootstrap `MPAS` for a repository owned by an GitHub organization, +it is recommended to create a dedicated GitHub user for `MPAS` and use that user to bootstrap +the repository. + +Run the bootstrap for a repository owned by a GitHub organization: + +```bash +mpas bootstrap github \ + --owner= \ + --repository= \ + --path=clusters/my-cluster \ + --dev +``` + +## Bootstrap for Gitea + +### Gitea API token + +For accessing the Gitea API, the boostrap command requires a Gitea API token +with administration permissions. + +The Gitea API Token can be exported as an environment variable: + +```bash +export GITEA_TOKEN= +``` + +If the `GITEA_TOKEN` environment variable is not set, the `MPAS Bootstrap` command will prompt +for the Gitea API token. + +{{% alert color="danger" title="API Token secret" %}} +Note that the Gitea API Token is stored in the cluster as a **Kubernetes Secret** named `flux-system` +inside the `flux-system` namespace. +{{% /alert %}} + +### Personal account + +Run bootstrap for a repository on your personal Gitea account: + +```bash +mpas bootstrap gitea \ + --owner= \ + --repository= \ + --path=clusters/my-cluster \ + --dev \ + --personal +``` + +If the specified repository does not exist, the `MPAS Bootstrap` command will create it +as a private repository. If you wish to create a public repository, you can use the `--private=false` +flag. + +### Organization + +If you want to bootstrap `MPAS` for a repository owned by an Gitea organization, +it is recommended to create a dedicated Gita user for `MPAS` and use that user to bootstrap +the repository. + +Run the bootstrap for a repository owned by a Gitea organization: + +```bash +mpas bootstrap gitea \ + --owner= \ + --repository= \ + --path=clusters/my-cluster \ + --dev +``` + + +## Bootstrap for an air-gapped environment + +If you want to bootstrap `MPAS` for a repository in an air-gapped environment, only Gitea +is supported at the moment. + +### Export the bootstrap components bundle + +To bootstrap `MPAS` in an air-gapped environment, you need to export the bootstrap components +bundle from the `MPAS` default registry. + +```bash +mpas bootstrap \ + --export \ + --export-path=/tmp +``` + +The above command will export the bootstrap components archive to `/tmp/mpas-bundle.tar.gz`. + +It is then possible to import the bootstrap components bundle in an air-gapped environment +registry and use it to bootstrap `MPAS` for a repository in that environment. + +```bash +mpas bootstrap gitea \ + --owner= \ + --repository= \ + --from-file=/tmp/mpas-bundle.tar.gz \ + --registry= \ + --path=clusters/my-cluster \ + --dev +``` + +The above command will copy the bootstrap components from the bundle archive to the specified +air-gapped registry and bootstrap `MPAS` for the specified repository. diff --git a/content/en/mpas/overview/installation.md b/content/en/mpas/overview/installation.md index 4b876c18..0e9df2c6 100644 --- a/content/en/mpas/overview/installation.md +++ b/content/en/mpas/overview/installation.md @@ -12,7 +12,7 @@ toc: true ## Install using Binaries -To install the MPAS CLI you can download binaries for major platforms from the GitHub [releases page](https://github.com/open-component-model/mpas/releases). +To install the MPAS CLI, you can download the binaries for major platforms from the GitHub [releases page](https://github.com/open-component-model/mpas/releases). ## Homebrew You can also install via [homebrew](https://brew.sh/) for macOS and Linux: From 61644c5011fd68ac8e40dbcded1281e33473ff65 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Wed, 20 Sep 2023 16:31:31 +0200 Subject: [PATCH 5/9] some more changes --- content/en/mpas/getting_started.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/content/en/mpas/getting_started.md b/content/en/mpas/getting_started.md index fdc97cc2..87b88bbd 100644 --- a/content/en/mpas/getting_started.md +++ b/content/en/mpas/getting_started.md @@ -66,16 +66,18 @@ This command will create a new Github repository called `mpas-bootstrap` and boo MPAS to your Kubernetes cluster. The following components will be installed: - [Flux](https://fluxcd.io/docs/components/): A Kubernetes operator that will install and manage the other components. -- [Ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes operator - that enable the automated deployment of software using the Open Component Model and Flux. -- [Git-controller](https://github.com/open-component-model/git-controller): A - Kubernetes controller that will create Pull Requests in the target Github repository +- [ocm-controller](https://github.com/open-component-model/ocm-controller): A Kubernetes controller + that enables the automated deployment of software components using the Open Component Model and Flux. +- [git-controller](https://github.com/open-component-model/git-controller): A + Kubernetes controller that will create pull requests in the target Github repository when changes are made to the cluster. -- [Replication-controller](https://github.com/open-component-model/git-controller): -- [MPAS-product-controller](https://github.com/open-component-model/mpas-product-controller): -- [MPAS-project-controller](https://github.com/open-component-model/mpas-project-controller): +- [replication-controller](https://github.com/open-component-model/git-controller): A Kubernetes controller that + keeps keep component versions in the cluster up-to-date with a version defined by the consumer in the `ComponentSubscription` resource. +- [mpas-product-controller](https://github.com/open-component-model/mpas-product-controller): A Kubernetes controller, responsible for creating a product. Reconciles the `Product` resource. +- [mpas-project-controller](https://github.com/open-component-model/mpas-project-controller): A Kubernetes controller responsible for bootstrapping a whole project. Creates relevant access credentials, service accounts, roles and the main GitOps repository and +reconciles the `Project` resource. -The output is similar to the following: +The output of the bootstrap is similar to the following: ```bash Running mpas bootstrap ... @@ -93,8 +95,8 @@ Bootstrap completed successfully! ``` After completing the bootstrap process, the target github repository will contain -yaml manifests for the components to be installed on the cluster. The cluster will -also have the components installed. Furthermore the installed `Flux` components will +yaml manifests for the components to be installed on the cluster and Flux will +apply all of them to get the components installed. Furthermore the installed `Flux` components will be configured to watch the target github repository for changes in the path `./clusters/my-cluster`. #### Clone the git repository @@ -119,7 +121,7 @@ and `ocm-system` namespaces. You can use [syncing-secrets-across-namespaces](htt ### Deploy podinfo application The [podinfo application](https://github.com/stefanprodan/podinfo) has been packaged -as an ocm component and can be retrieved from [Github](ghcr.io/open-component-model/podinfo). +as an OCM component and can be retrieved from [Github](ghcr.io/open-component-model/podinfo). - - - 1. Create a secret containing your GitHub credentials that will be used by MPAS to create your project repository. @@ -195,7 +174,7 @@ spec: EOF ``` -Then, apply the project to the clustern in a gitOps fashion: +Then, apply the project to the cluster in a gitOps fashion: ```bash git add --all && git commit -m "Add podinfo project" && git push @@ -294,10 +273,6 @@ defined registry in the `spec.source.url` to the `spec.destination.url` registry The target will define where the application will be installed - ```bash cat <> ./targets/podinfo.yaml @@ -323,7 +298,7 @@ git add --all && git commit -m "Add a target for podinfo" && git push `Flux` will detect the changes and apply the target to the cluster. -7. Deploy the podinfo application +1. Deploy the podinfo application In order to deploy the podinfo application, we need to create a `ProductDeploymentGenerator` resource: @@ -354,8 +329,6 @@ git add --all && git commit -m "Add podinfo deployment generator" && git push This will create a pull request in the project repository with the `ProductDeployment` resource that will deploy the podinfo application. - - Go to the project repository and retrieve the pull request. It should contain a `ProductDeployment` declaration that provides the configuration and all steps needed to deploy the product, as well as a `values.yaml` file. The `values` file