diff --git a/website/docs/enterprise/getting-started/install-enterprise-azure.mdx b/website/docs/enterprise/getting-started/install-enterprise-azure.mdx new file mode 100644 index 0000000000..e0f7351bea --- /dev/null +++ b/website/docs/enterprise/getting-started/install-enterprise-azure.mdx @@ -0,0 +1,284 @@ +--- +title: Azure and Weave GitOps Enterprise Installation +hide_title: true +--- + +import TierLabel from "@site/docs/_components/TierLabel"; +import oauthBitbucket from '/img/oauth-bitbucket.png'; +import oauthAzureDevOps from '/img/oauth-azure-devops.png'; +import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png'; + +# Azure and Weave GitOps Enterprise Installation + +Once you successfully create your Kubernetes cluster in Azure Marketplace, follow these steps to Install Weave GitOps Enterprise. These instructions apply to both Azure AKS and Azure ARC clusters—they'll behave in the same way. + +:::tip +If you have already installed [Flux](https://fluxcd.io/flux/cmd/), then Azure Flux will refuse to install. +::: + +## 1. Choose the “GitOps” option in the Marketplace + +Search for Weave GitOps Enterprise in the "Extensions + Applications" of the [Azure Marketplace](https://portal.azure.com/signin/index/). Click the "GitOps" option. This will take you to a screen that presents a first-class item called `Type: Flux v2`. + +Click GitOps => Create. + +Add the config name, namespace (default), scope: cluster, type (Flux v2), and continuous reconciliation option. Your entries should look like this: +- Configuration: flux-system +- Namespace: flux-system +- Scope: Cluster + +All of the displayed properties for the Flux objects screen are the same as what you'd supply to Flux bootstrap. + +### Optional: Install CAPZ, the CAPI Provider + +If you are planning to manage or connect CAPI clusters to the WE service make sure you first install the CAPI provider. Then during the WE installation process be sure to select the "Enable CAPI support" checkbox. + +## 2. Apply the Entitlements Secret + +Contact sales@weave.works for a valid entitlements secret. This will come in the form of a file “entitlements.yaml”. Apply it to the cluster: + +``` +kubectl apply -f entitlements.yaml +``` + +## 3. Configure Access for Writing to Git from the UI + +*(This section is the same as what you'll find in the main WGE install documentation.)* + +Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps. + + + +GitHub requires no additional configuration for OAuth Git access + + + +Create a GitLab OAuth application that will request `api` permissions to create pull requests on your behalf. + +Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html). + +The application should have at least these scopes: + +- `api` +- `openid` +- `email` +- `profile` + +Add callback URLs to the application for each address the UI will be exposed on, e.g.: + +- `https://localhost:8000/oauth/gitlab` for port-forwarding and testing +- `https://git.example.com/oauth/gitlab` for production use + +Save your application, taking note of the **Client ID** and **Client Secret**. Save +them into the `git-provider-credentials` secret, along with: + +- `GIT_HOST_TYPES` to tell WGE that the host is gitlab +- `GITLAB_HOSTNAME` where the OAuth app is hosted + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="GITLAB_CLIENT_ID=13457" \ + --from-literal="GITLAB_CLIENT_SECRET=24680" \ + --from-literal="GITLAB_HOSTNAME=git.example.com" \ + --from-literal="GIT_HOST_TYPES=git.example.com=gitlab" +``` + + + + +Create a new [incoming application link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html) from +the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL +should be set to `/oauth/bitbucketserver`. You will also need to select permissions for the application. The minimum set of +permissions needed for WGE to create pull requests on behalf of users is `Repositories - Write`. An example of configuring these settings is shown below. + +
+ + + +
Configuring a new incoming application link
+
+ + +Save your application and take note of the **Client ID** and **Client Secret**. Save +them into the `git-provider-credentials` secret, along with: + +- `GIT_HOST_TYPES` to tell WGE that the host is bitbucket-server +- `BITBUCKET_SERVER_HOSTNAME` where the OAuth app is hosted + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \ + --from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \ + --from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \ + --from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server" +``` + +If the secret is already present, use the following command to update it using your default editor: + +```bash +kubectl edit secret generic git-provider-credentials --namespace=flux-system +``` + +:::info + +If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: `GIT_HOST_TYPES=git.example.com:7990=bitbucket-server` + +::: + + + + + +Navigate to [VisualStudio](https://app.vsaex.visualstudio.com/app/register) and register a new application, as explained in the [docs](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops#1-register-your-app). Set the authorization callback URL and select which scopes to grant. Set the callback URL to `/oauth/azuredevops`. + +Select the `Code (read and write)` scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below. + +
+ +
Creating a new application
+
+ +After creating your application, you will be presented with the application settings. Take note of the `App ID` and `Client Secret` values—you will use them to configure WGE. + +
+ +
Application settings
+
+ +In your cluster, create a secret named `git-provider-credentials` that contains the `App ID` and `Client Secret` values from the newly created application. + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="AZURE_DEVOPS_CLIENT_ID=" \ + --from-literal="AZURE_DEVOPS_CLIENT_SECRET=" +``` + +WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me. + + + + +## 4. Configure Your Password + +First, install the Weave GitOps Enterprise CLI tool. To do this, you can use either brew or curl. + + + + +```bash +brew install weaveworks/tap/gitops-ee +``` + + + + + +```bash +curl --silent --location "https://artifacts.wge.dev.weave.works/releases/bin/0.27.0/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp +sudo mv /tmp/gitops /usr/local/bin +gitops version +``` + + + + +Now, to login to the WGE UI, generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster. There are several different ways to generate a bcrypt hash. Here, we'll use `gitops get bcrypt-hash` from our GitOps CLI. + +```bash +PASSWORD="" +echo -n $PASSWORD | gitops get bcrypt-hash | kubectl create secret generic cluster-user-auth -n flux-system --from-literal=username=wego-admin --from-file=password=/dev/stdin +``` + +A validation to know it’s working: + +```bash +kubectl get secret -n flux-system cluster-user-auth +``` + +## 5. Install Weave GitOps Enterprise to Your Cluster + +First, you'll get taken to the Weaveworks portal on the Azure platform, which provides your subscription details. + +Search for Weave GitOps. Pick "View private products" and choose WGE. Fill out the forms, selecting your cluster, then choose "Review and Create". + +## 6. Apply Extra Configuration + +Additional configuration is done through an optional ConfigMap: + +``` +apiVersion: v1 +kind: ConfigMap +metadata: + name: cluster-service-extra-config + namespace: flux-system +data: + # disable TLS +NO_TLS: "true" +``` + +Apply the configuration with: + +``` +kubectl apply -f cluster-service-extra-config.yaml + +# restart the clusters-service for changes to take effect +kubectl -n flux-system rollout restart deploy/weave-gitops-enterprise-mccp-cluster-service +``` + +### Available Configuration Options + +| value | default | description | +|---|---|---| +| `NO_TLS` | `"false"` | disable TLS | +| `CLUSTER_NAME` | `"management"` | name of the management cluster | +| `AUTH_METHODS` | `"token-passthrough,user-account"` | Which auth methods to use, valid values are 'oidc', 'token-pass-through' and 'user-account' | +| `OIDC_ISSUER_URL` | `"token-passthrough,user-account"` | The URL of the OpenID Connect issuer | +| `OIDC_CLIENT_ID` | `"token-passthrough,user-account"` | The client ID for the OpenID Connect client | +| `OIDC_CLIENT_SECRET` | `"token-passthrough,user-account"` | The client secret to use with OpenID Connect issuer | +| `OIDC_REDIRECT_URL` | `"token-passthrough,user-account"` | The OAuth2 redirect URL | +| `OIDC_TOKEN_DURATION` | `"1h"` | The duration of the ID token. It should be set in the format: number + time unit (s,m,h) e.g., 20m | +| `OIDC_CLAIM_USERNAME` | `"email"` | JWT claim to use as the user name. By default email, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as sub or name, depending on their provider | +| `OIDC_CLAIM_GROUPS` | `"groups"` | JWT claim to use as the user's group. If the claim is present it must be an array of strings | +| `CUSTOM_OIDC_SCOPES` | `"groups, openid, email, profile"` | Customise the requested scopes for then OIDC authentication flow - openid will always be requested | + +## 7. Check That It Works + +Go to the "services and ingresses" tab in the Azure portal and look for signs that the UI installed. + +## Troubleshooting + +WGE will try and automatically install Flux on a new cluster. If this fails for some reason, or if you need a custom Flux installation, you can manually install it before installing WGE. + +Click "Next" and add: +- Source Kind: Git repository +- Repository URL: [your repository URL here] +- Reference Type: Branch +- Repository Type: Private + +And under the "Authentication" section: +- Authentication Source: Provide Authentication here +- SSH Key Authentication: Let the operator generate SSH Keys +- HTTPS User: YOUR_GITHUB_USERNAME +- HTTPS Key: YOUR_GITHUB_USER_PAT (Get one at [this link](https://github.com/settings/tokens). It's not the most secure method, but the easiest to get going.) + +Click "Next". You'll see an option to create a Kustomisation, which is optional. To create one: +- Click Create +- Instance name: flux-system +- Path: clusters/default/demo3-azure-flux +- Prune: Ticked + +Click "Save". Then clicking "Next", which will give you a summary so you can review your input. Then click "Create". It will take about five minutes to deploy. + +You'll get to a new screen, which at the top-right shows "Notifications" and will display creation of the Flux configuration. When your deployment succeeds, go to the resource and pin to your dashboard. Then go to your terminal to see if it works in kubectl. In the terminal you'll get the GitRepository and Kustomizations. You should then get a green "succeeded" checkmark. + +The Kustomisations screen does not provide an option to inspect the path/target namespace—you have to supply the target Namespace in the Kustomization object. + +## Next Steps + +From this point, you can follow our generalized WGE installation instructions to [configure TLS](./install-enterprise.mdx#tls-configuration) and log into the UI. Installing the Azure Marketplace product installs the Helm chart. diff --git a/website/docs/enterprise/getting-started/join-cluster-azure-flux.mdx b/website/docs/enterprise/getting-started/join-cluster-azure-flux.mdx new file mode 100644 index 0000000000..a567f4e095 --- /dev/null +++ b/website/docs/enterprise/getting-started/join-cluster-azure-flux.mdx @@ -0,0 +1,215 @@ +--- +title: Join a Cluster with Azure Flux +hide_title: true +--- + +import TierLabel from "@site/docs/_components/TierLabel"; + +# Joining a Cluster with Azure Flux + +## Prerequisites + +See also our [guide to installing Weave GitOps Enterprise on Azure](install-enterprise-azure.mdx): +- An Azure cluster deployed with either the Azure Portal or Azure CLI tools. +- Azure Flux add-on deployed by adding a GitOps configuration, either via the Azure Portal or the CLI tool. + +Note that this documentation applies to both Azure AKS and Azure ARC clusters. + +## Initial Status + +The Azure cluster already has the Azure Flux add-on installed. This differs from [CNCF Flux](https://fluxcd.io/) in that there are two additional controllers: +- fluxconfig-agent +- fluxconfig-controller + +These controllers have CRDs that define the version of Flux and any Flux Kustomizations that are managed via the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). + +The CRDs are all apiVersion: clusterconfig.azure.com/v1beta1. + +The Kinds are: +- FluxConfig +- FluxConfigSyncStatus + +The FluxConfig Kind configures Flux itself and creates any Kustomizations that refer to a single-source GitRepository. This guide assumes that this process is already completed and that a top-level Kustomization has been configured for the fleet repo cluster directory already set up at +`clusters/default/CLUSTER_NAME/manifests`. + +The CRDs that this FluxConfig generates are Flux CRDs, as follows: +- GitRepositories +- Kustomizations + +These generated resources are viewable through Weave GitOps Enterprise. + +Weave GitOps itself is deployed by Flux using a HelmRelease that pulls the Helm Chart. It doesn’t need to install Flux, as it is assumed that Flux is already deployed. Therefore it can use the Azure Flux add-on, which poses no conflicts with WGE itself. + +Incompatibilities exist between the Azure Flux add-on and CNCF Flux. They should not be run at the same time, on the same cluster, due to conflicts in the CRD management. If the Flux bootstrapping process IS run on a cluster with Azure Flux add-on, it will override the Azure Flux add-on with the Flux version used in the bootstrap. Also, it would add Flux manifests to the source Git repository. This would be undesirable. + +Azure Flux add-on-enabled clusters keep the Azure Flux add-on in place. + +## Joining a Cluster to WGE + +### Setting up a Service Account + +To join a cluster, you'll set up a service account with permissions and create a kubeconfig for the service account. This service account does not need cluster admin permissions unless you are bootstrapping Flux into the cluster. The bootstrapping process will either be A) carried out before joining the cluster to WGE; or B) configured specifically for Flux to be bootstrapped into the cluster from WGE. + +If you already have Flux running, you can create the service account in your fleet repo: + +1. Create a service account file: + +
Expand to see role manifests + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: wgesa + namespace: default +``` + +``` +apiVersion: v1 +kind: Secret +type: kubernetes.io/service-account-token +metadata: + name: wgesa-secret + namespace: default + annotations: + kubernetes.io/service-account.name: "wgesa" +``` + +
+ +2. Create a roles file: + +
Expand to see role manifests + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: impersonate-user-groups +subjects: + - kind: ServiceAccount + name: wgesa + namespace: default +roleRef: + kind: ClusterRole + name: user-groups-impersonator + apiGroup: rbac.authorization.k8s.io +``` + +``` +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: user-groups-impersonator +rules: + - apiGroups: [""] + resources: ["users", "groups"] + verbs: ["impersonate"] + - apiGroups: [""] + resources: ["namespaces"] + verbs: ["get", "list"] +``` + +
+ +3. Commit to your fleet repo to sync. + +4. Create a secret to store the kubeconfig, and a GitopsCluster object in the WGE management cluster that points to the kubeconfig secret. This allows you to connect to the target cluster and read various Kubernetes objects—including the Flux objects, such as: +- GitRepositories +- HelmReleases +- Kustomizations +- Providers +- Alerts +- Receivers + +Kubernetes 1.24+ [will not create secrets for Service Accounts for you](https://stackoverflow.com/questions/75692230/secret-for-a-kubernetes-service-accounts-is-not-getting-created), so you have to add it yourself. + +5. Add a new secret for the service account by adding to the service account yaml file in step 1. + +6. Create a kubeconfig secret. We'll use a helper script to generate the kubeconfig, and then save it into `static-kubeconfig.sh`: + +
Expand to see script + + ```bash title="static-kubeconfig.sh" + #!/bin/bash + + if [[ -z "$CLUSTER_NAME" ]]; then + echo "Ensure CLUSTER_NAME has been set" + exit 1 + fi + + if [[ -z "$CA_CERTIFICATE" ]]; then + echo "Ensure CA_CERTIFICATE has been set to the path of the CA certificate" + exit 1 + fi + + if [[ -z "$ENDPOINT" ]]; then + echo "Ensure ENDPOINT has been set" + exit 1 + fi + + if [[ -z "$TOKEN" ]]; then + echo "Ensure TOKEN has been set" + exit 1 + fi + + export CLUSTER_CA_CERTIFICATE=$(cat "$CA_CERTIFICATE" | base64) + + envsubst < + +7. Create a secret for the generated kubeconfig in the WGE management cluster: + + ```bash + kubectl create secret generic demo-01-kubeconfig \ + --from-file=value=./demo-01-kubeconfig + ``` + +You can also take care of this step in WGE's [Secrets UI](https://docs.gitops.weave.works/docs/next/secrets/intro/), setting up a a secret in [SOPS](https://docs.gitops.weave.works/docs/next/secrets/setup-sops/) or [ESO](https://docs.gitops.weave.works/docs/next/secrets/setup-eso/). + +Flux CRDs are compatible with the Azure Flux Configuration CRDs. This means that there are no compatibility issues between WGE and Azure Flux. + +8. Create a GitopsCluster object. It must NOT be bootstrapped. Remove the annotation for bootstrap so it will not deploy Flux. + +9. Commit to your fleet repo and sync. + +10. Log in to your WGE management cluster to see if the cluster has appeared. + +## Using WGE to Deploy Clusters + +### With Cluster API + +MSFT maintains CAPZ, the Azure CAPI provider. Currently there is no support for Azure Flux. A CAPI-based cluster will continue to run the Flux bootstrap process on cluster creation when managed by WGE, because there is no Azure Flux option. + +### With Terraform Provider + +WGE uses [TF-controller](https://github.com/weaveworks/tf-controller) to deploy Terraform resources. For WGE to use the cluster as a target requires A) a resource created in the management cluster and B) a kubeconfig that maps to a service account in the target cluster. The Terraform cluster build typically creates this service account and then outputs to a secret store or local secret so that WGE can use it as a cluster. The Flux bootstrap process can be initiated directly with the Flux Terraform module, which deploys CNCF Flux to the target cluster. + +Alternatively, you can apply an Azure Policy to provide the Azure Flux add-on. This is an example of how you can use the policy controls. This means you could come across clusters that are deployed with Terraform with the Azure Flux add-on already installed and would not run the Flux bootstrap process. + +Either way, it is typical that Terraform-deployed clusters do not run the Flux bootstrap process at all, because it is usually already installed. + +### With Crossplane + +The Azure Flux add-on is supported under [Crossplane](https://www.crossplane.io/)-deployed Azure clusters. Any clusters deployed with Crossplane that have the Azure Flux add-on enabled would also be added to WGE without running the bootstrap process. diff --git a/website/docs/guides/cert-manager.md b/website/docs/guides/cert-manager.md index 40aa760de3..521a0293a2 100644 --- a/website/docs/guides/cert-manager.md +++ b/website/docs/guides/cert-manager.md @@ -103,4 +103,4 @@ spec: Once this `ClusterIssuer` resource is installed, the cluster is now configured to request and use certificates generated by cert-manager. -This could be manually requested through the creation of a [Certificate resource](https://cert-manager.io/docs/usage/certificate/#creating-certificate-resources) or configured to be automatic, as shown in our [Configuring OIDC with Dex and GitHub](./setting-up-dex.md) guide. +This could be manually requested through the creation of a [Certificate resource](https://cert-manager.io/docs/usage/certificate/#creating-certificate-resources) or configured to be automatic, as shown in our [WGE installation](../enterprise/getting-started/install-enterprise.mdx#securing-access-to-the-dashboard)) guide. diff --git a/website/docs/open-source/getting-started/install-OSS.mdx b/website/docs/open-source/getting-started/install-OSS.mdx index fe572ef4a2..2f3c1dc0eb 100644 --- a/website/docs/open-source/getting-started/install-OSS.mdx +++ b/website/docs/open-source/getting-started/install-OSS.mdx @@ -7,7 +7,7 @@ pagination_next: open-source/getting-started/ui-OSS # Step 1: Install Weave GitOps Open Source on Your Cluster :::tip -These instructions only apply to Weave GitOps Open Source. To install Weave GitOps Enterprise, [go here][ee-install]. +These instructions only apply to Weave GitOps Open Source. To install Weave GitOps Enterprise, [go here](../../enterprise/getting-started/install-enterprise.mdx). ::: This page covers Weave GitOps Open Source installation and is adapted from the [Flux - Getting Started](https://fluxcd.io/docs/get-started/) guide. @@ -17,7 +17,7 @@ If you haven't already, please check out our [Introduction to Weave GitOps](../. ## Prerequisites Before you can install Weave GitOps Open Source, you will need: -- A [GitHub][github] account and [personal access token with repo permissions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) +- An account with a Git provider like GitHub or GitLab, along with a personal access token with repo permissions; if you're using GitHub, for example, [go here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) - Your Git client configured properly (if using GitHub, for example, then review their docs on [setting your username](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git#setting-your-git-username-for-every-repository-on-your-computer) and [your email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-email-address-for-every-repository-on-your-computer)) @@ -218,7 +218,6 @@ Find the full Chart reference [here](../../references/helm-reference.md). Now let's [explore the Weave GitOps Open Source UI](./ui-OSS.mdx). Then, we'll deploy an application. -[ee-install]: ../../enterprise/getting-started/install-enterprise.mdx [kind]: https://kind.sigs.k8s.io/docs/user/quick-start/ [github]: https://github.com [pat]: https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line diff --git a/website/sidebars.js b/website/sidebars.js index 561ee8e3bd..a020f2dbe4 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -42,8 +42,10 @@ 'enterprise/getting-started/install-enterprise', 'enterprise/getting-started/install-enterprise-airgap', 'enterprise/getting-started/releases-enterprise', - ], - }, + 'enterprise/getting-started/install-enterprise-azure', + 'enterprise/getting-started/join-cluster-azure-flux', + ], + }, { type: 'link', label: 'Version Archives', diff --git a/website/versioned_docs/version-0.29.0/guides/cert-manager.md b/website/versioned_docs/version-0.29.0/guides/cert-manager.md index 40aa760de3..3317b926a6 100644 --- a/website/versioned_docs/version-0.29.0/guides/cert-manager.md +++ b/website/versioned_docs/version-0.29.0/guides/cert-manager.md @@ -103,4 +103,4 @@ spec: Once this `ClusterIssuer` resource is installed, the cluster is now configured to request and use certificates generated by cert-manager. -This could be manually requested through the creation of a [Certificate resource](https://cert-manager.io/docs/usage/certificate/#creating-certificate-resources) or configured to be automatic, as shown in our [Configuring OIDC with Dex and GitHub](./setting-up-dex.md) guide. +This could be manually requested through the creation of a [Certificate resource](https://cert-manager.io/docs/usage/certificate/#creating-certificate-resources) or configured to be automatic, as shown in our [WGE installation](../enterprise/getting-started/install-enterprise.mdx#securing-access-to-the-dashboard) guide.