diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx index c1d311705a..919fa974e5 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx @@ -1,7 +1,8 @@ --- -title: Manual Bootstrapping -hide_title: true -pagination_next: enterprise/getting-started/releases-enterprise +title: Manually +hide_title: false +pagination_prev: enterprise/getting-started/install-enterprise-getting-started +pagination_next: enterprise/getting-started/install-enterprise-onboard-platform-engineers toc_max_heading_level: 4 --- @@ -14,18 +15,19 @@ import oauthBitbucket from '/img/oauth-bitbucket.png'; import oauthAzureDevOps from '/img/oauth-azure-devops.png'; import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png'; -# Manual Bootstrap +# Getting Started Manually +This guide will walk you through to manual getting started [bootstrapping](../install-enterprise-getting-started/#bootstrapping) route for Weave GitOps Enterprise. +:::caution This guide aims to easy discovery or day-0 experiences. -## Bootstrap Flux - -This stage is about bootstrapping Fux which involves deploying Flux into the management cluster and configure it to reconcile your Git repository. +Ensure you complete the [rest of the journeys](../install-enterprise-getting-started/) if you aim to onboard other Platform Engineers or Developers. +::: -The `flux bootstrap` command enables you to deploy Flux on a cluster the GitOps way. See the different -option [Flux bootstrap](https://fluxcd.io/docs/cmd/flux_bootstrap/) documentation. +## Bootstrap Flux -Two examples using [`flux bootstrap git`](https://fluxcd.io/flux/cmd/flux_bootstrap_git/) are: +This stage is about bootstrapping Fux which involves deploying Flux into the management cluster and configure it to reconcile your Git repository. The `flux bootstrap` command enables you to deploy Flux on a cluster the GitOps way. +There are different ways to execute [Flux bootstrap](https://fluxcd.io/docs/cmd/flux_bootstrap/). Two examples using [`flux bootstrap git`](https://fluxcd.io/flux/cmd/flux_bootstrap_git/) are: ```bash # Run bootstrap for a Git repository and authenticate using a password @@ -34,7 +36,8 @@ flux bootstrap git --url="https://example.com/repository.git" --"password=passwo # Run bootstrap for a Git repository with a private key and password flux bootstrap git --url="ssh://git@example.com/repository.git" --private-key-file="path/to/private.key" --password="password" --path="clusters/my-cluster" ``` -### Entitlements + +## Entitlements Weave GitOps Enterprise Entitlement is your obtained license to use our product. The Entitlements file is a Kubernetes secret that contains your licence. To get the entitlement secret please contact *sales@weave.works*, then apply it on your management cluster with the name `weave-gitops-enterprise-credentials` under `flux-system` namespace. @@ -42,89 +45,15 @@ To get the entitlement secret please contact *sales@weave.works*, then apply it ```bash kubectl apply -n flux-system -f entitlements.yaml ``` - -:::info Verify Entitlements - -The following verification is done when bootstrapping using the CLI: -- The secret exists on the management cluster -- It has a valid content -- Entitlement is not expired - -::: - -### Authentication +## Authentication There are two supported authentication methods for Weave GitOps Enterprise: +- `Cluster User`: only recommended for development environments or if you need to activate emergency access to a damaged cluster. However, it is an option if an OIDC provider is not available. - `OIDC`: allows you to control permissions for existing users and groups that have already been configured to use OIDC. OIDC decouples the need to manage user lists from the application, allowing it to be managed via a central system designed for that purpose (i.e. the OIDC provider). OIDC also enables the creation of groups—either via your provider's own systems or by using a connector like [Dex](#configuring-oidc-with-dex-and-github). -- `Cluster User`: only recommended for development environments or if you need to activate emergency access to a damaged cluster. However, it is an option if an OIDC provider is not available. - -The both work with standard Kubernetes RBAC for authorization. - - - - -In interactive mode you will be guided to setup authentication for both Cluster User and OIDC. -In non-interactive mode you have the following flags to configure authentication: - -```bash -# setup Cluster User 'wego-admin' with password 'admin123' -gitops bootstrap --password="admin123" - -# setup OIDC authentication -gitops bootstrap --discovery-url="https://example.com/.well-known/openid-configuration" \ ---client-id="weave-gitops-enterprise", --client-secret="clientSecretWeaveGitopsEnterprise" -``` - -For more information about the CLI configurations, check the below sections [here](#cli-configurations) - - - - -You may decide to give your engineering teams access to the WGE dashboard so they can view and manage their workloads. In this case, you will want to secure dashboard access and restrict who can interact with it. Weave GitOps Enterprise integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the dashboard users' permissions. - -OIDC extends the OAuth2 authorization protocol by including an additional field (ID Token) that contains information (claims) about a user's identity. After a user successfully authenticates with the OIDC provider, Weave GitOps Enterprise uses this information to impersonate the user in any calls to the Kubernetes API. This allows cluster administrators to use RBAC rules to control access to the cluster and the dashboard. - -For more specific examples of how to setup OIDC with Weave GitOps, see [this guide](../../../guides/oidc/). - -If you run into issues setting up OIDC with Weave GitOps, please refer to the [`gitops check oidc-config` command](../../../references/cli-reference/gitops_check_oidc-config/) - -To login via your OIDC provider, create a Kubernetes secret to store the OIDC configuration. This configuration consists of the following parameters: - -| Parameter | Description | Default | -| ------------------| -------------------------------------------------------------------------------------------------------------------------------- | --------- | -| `issuerURL` | The URL of the issuer; typically, the discovery URL without a path | | -| `clientID` | The client ID set up for Weave GitOps in the issuer | | -| `clientSecret` | The client secret set up for Weave GitOps in the issuer | | -| `redirectURL` | The redirect URL set up for Weave GitOps in the issuer—typically the dashboard URL, followed by `/oauth2/callback ` | | -| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | -| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | -| `oidcUsernamePrefix` | The prefix added to users when impersonating API calls to the Kubernetes API, equivalent to --oidc-username-prefix | | -| `oidcGroupsPrefix` | The prefix added to groups when impersonating API calls to the Kubernetes API, equivalent to --oidc-groups-prefix | | - -Ensure that your OIDC provider has been set up with a client ID/secret and the dashboard's redirect URL. - -Create a secret named `oidc-auth` in the `flux-system` namespace with these parameters set: - -```bash -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL="oidc-issuer-url" \ - --from-literal=clientID="client-id" \ - --from-literal=clientSecret="client-secret" \ - --from-literal=redirectURL="redirect-url" \ - --from-literal=tokenDuration="token-duration" -``` - -:::warning -Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted. -::: -Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in. - - - +**Getting Started with a Cluster User** :::danger Important This is an **insecure** method of accessing your dashboard. We only see useful in any of the following scenarios: @@ -136,8 +65,6 @@ For secure and fully-featured authentication we **strongly recommend** using an before onboarding other users. ::: -**Configuring the Cluster User** - Before you log in via the Cluster User account, you need to generate a bcrypt hash for your chosen password and store it as a secret in Kubernetes. There are several different ways to generate a bcrypt hash. This guide uses `gitops get bcrypt-hash` from our CLI. Generate the password by running: @@ -158,19 +85,17 @@ kubectl create secret generic cluster-user-auth \ --from-literal=password='$2a$10$OS5NJmPNEb13UTOSKngMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q' ``` -You should now be able to login via the cluster user account using your chosen username and password. +Use these credentials to login as `ClusterUser` via the UI. -See how to harden this section in [Day 1 Cluster User](#cluster-user). +:::caution - - +Ensure your [authentication is fit for production](../install-enterprise-onboard-platform-engineers#authentication) before onboarding other Platform Engineers or Developers. +::: -### Authorization +## Authorization Weave GitOps Enterprise works with standard [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -to define what actions can a subject do-over the existing resources. - -Weave GitOps requires authorization for the following subjects: +to define what actions can a subject do-over the existing resources. Weave GitOps requires authorization for the following subjects: - **Weave GitOps Users:** previously authenticated via either OIDC or Cluster User. - **Weave GitOps Service Account:** which talks to Kubernetes for user operations via [Impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). @@ -227,43 +152,8 @@ in terms of least-privilege access to be tackled as part of https://github.com/w // TODO add me explorer access rules debug view -See how to harden this section in [Day 1 Cluster User](#cluster-user). - - -OIDC is highly context dependent, during bootstrapping no RBAC resources are created but expected to exist -in your configuration repo. In case that they dont exist, you will be able to login but will have limited access to the resources. - -// TODO refactor as general pattern not only in the context of OIDC - -A common pattern called `Bases` helps you getting started with OIDC RBAC: - -1. Create a folder in your Git repo in path like `clusters/bases`. -2. Add your RBAC resources into the folder `clusters/bases/rbac`. -3. Create a folder `clusters/management` adding the following `Kustomization`: - -```yaml title="clusters/management/clusters-bases-kustomization.yaml" -apiVersion: kustomize.toolkit.fluxcd.io/v1beta2 -kind: Kustomization -metadata: - creationTimestamp: null - name: clusters-bases-kustomization - namespace: flux-system -spec: - interval: 10m0s - path: clusters/bases - prune: true - sourceRef: - kind: GitRepository - name: flux-system -``` - -Save these two files in your Git repository, then commit and push. Flux will deploy the kustomization and the RBAC -resources will be created. -See how to harden this section in [Day 1](#oidc-authorization). - - **Weave GitOps Service Account** @@ -280,24 +170,15 @@ They are generated during Flux Bootstrapping. More information about Flux Author -### Install WGE - -We install Weave GitOps Enterprise via Flux Helm Release that you could deploy via the CLI or manually: - - - +:::caution -You could configure this stage by using the following flags and examples: +Ensure your [authorization is fit for production](../install-enterprise-onboard-platform-engineers#authorization) before onboarding other Platform Engineers or Developers. +::: - ```bash - # Configure bootstrapping to install WGE version '0.37.0' - gitops bootstrap --version="0.37.0" - ``` +## Install WGE -For more information about the CLI configurations, check the below sections [here](#cli-configurations) +We install Weave GitOps Enterprise via Flux Helm Release that you could deploy via the CLI or manually: - - Download the following `HelmRelease` to `clusters/management/weave-gitops-enterprise.yaml`. @@ -337,689 +218,6 @@ git push Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the `flux-system` namespace to verify all pods are running. - - - - - -## Day 1: Customise and Complete - -Now that you have Weave GitOps Enterprise up and running, you might want to iterate your setup before opening to the rest of -the users. This section shows you the different options that you could configure to adapt Weave GitOps Enterprise to your needs. - -### Authorization - -#### Cluster User - -**User Permissions** - -By default, both a ClusterRole and Role are generated for the Cluster User. -Both have the same permissions, with the former being optional and the latter being -bound to the `flux-system` namespace (where Flux stores its resources by default). -The default set of rules are configured like this: - -```yaml -rules: - # Flux Resources - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: [ "notification.toolkit.fluxcd.io" ] - resources: [ "providers", "alerts" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["infra.contrib.fluxcd.io"] - resources: ["terraforms"] - verbs: [ "get", "list", "watch", "patch" ] - - # Read access for all other Kubernetes objects - - apiGroups: ["*"] - resources: ["*"] - verbs: [ "get", "list", "watch" ] -``` - -These permissions give the Cluster User Administrator-level powers. **We do not -advise leaving it active on production systems**. - -If required, the permissions can be expanded with the `rbac.additionalRules` field in the -[Helm Chart](../../references/helm-reference.md). - -Follow the instructions in the next section in order to configure RBAC correctly. - -#### OIDC - -// TODO Uses bases pattern to configure OIDC - -#### Weave GitOps Service Account - -This section covers the service account [permissions] -for the Weave GitOps application, which the WGE UI requires to work. -The default permissions will generate a cluster role that includes the permissions: - -```yaml -rules: -- apiGroups: [""] - resources: ["users", "groups"] - verbs: [ "impersonate" ] -- apiGroups: [""] - resources: [ "secrets" ] - verbs: [ "get", "list" ] -- apiGroups: [ "" ] - resources: [ "namespaces" ] - verbs: [ "get", "list" ] -``` - -These allow the pod to do three things: -* [Impersonate](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) the user and operate in the cluster as them -* Read the available namespaces; this is required to understand users' permissions -* Read the `cluster-user-auth` and `oidc-auth` secrets, the default secrets -to store the emergency cluster user account and OIDC configuration (see -[securing access to the dashboard](#securing-access-to-the-dashboard)) - -#### Impersonation - -The primary way Weave GitOps queries the Kube API is via `impersonation`. The permissions granted to users and groups that Weave GitOps -can impersonate will determine the scope of actions that WGE can take within your cluster. - -The application, not the cluster, authenticates the user, either via the [emergency -cluster user](#configuring-the-emergency-user) credentials or OIDC. Then it makes Kube API calls on the user's -behalf. This is equivalent to making a kubectl call like: - -```bash -$ kubectl get deployments --as aisha@example.com -``` - -Assuming the user `aisha@example.com` has permissions to get -deployments within the cluster, this will return those deployments. The same occurs -within the application, so properly configuring application -permissions is very important. Without proper restrictions the application can impersonate -very powerful `users` or `groups`. For example, the `system:masters` is a group -generally bound to the `cluster-admin` role, which can do anything. - -#### Get Namespaces - -The application itself uses get namespace permissions to pre-cache the list of -available namespaces. As the user accesses resources their permissions within -various namespaces is also cached to speed up future operations. - -#### Reading the `cluster-user-auth` and `oidc-auth` Secrets - -The `cluster-user-auth` and `oidc-auth` secrets provide information for authenticating -to the application. The former holds the username and bcrypt-hashed password -for the [emergency user](#configuring-the-emergency-user), and the latter holds OIDC configuration. - -The application needs to be able to access these secrets in order to -authenticate users. - -### User Permissions - -This section discusses the [Kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -needed by Weave GitOps application users and groups. At a minimum, a User should be bound to a Role in the `flux-system` namespace—which is where -Flux stores its resources by default—with the following permissions: - -```yaml -rules: - # Flux Resources - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: [ "notification.toolkit.fluxcd.io" ] - resources: [ "providers", "alerts" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["infra.contrib.fluxcd.io"] - resources: ["terraforms"] - verbs: [ "get", "list", "watch", "patch" ] - - # Read access for all other Kubernetes objects - - apiGroups: ["*"] - resources: ["*"] - verbs: [ "get", "list", "watch" ] -``` - -For a wider scope, the User can be bound to a ClusterRole with the same set. - -On top of this you can add other permissions to view WGE resources like `GitOpsSets` and `Templates`. - -#### Flux Resources - -The following table lists resources that Flux works with directly. - -| API Group | Resources | Permissions | -| ------------------------------ | ----------------------------------------------------------------------- | ---------------- | -| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch | -| helm.toolkit.fluxcd.io | Helm Releases | get, list, patch | -| source.toolkit.fluxcd.io | buckets, Helm charts, Git repositories, Helm repositories, OCI repositories | get, list, patch | -| notification.toolkit.fluxcd.io | providers, alerts | get, list | -| infra.contrib.fluxcd.io | [Terraform](https://github.com/weaveworks/tf-controller) | get, list, patch | - -Weave GitOps needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses before it can accurately display Flux state. The -`get` and `list` permissions facilitate this. - -The `patch` permissions are used for two features: to suspend and resume -reconciliation of a resource by modifying the 'spec' of a resource, -and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that `flux suspend`, -`flux resume`, and `flux reconcile` does on the CLI. - -#### Resources Managed via Flux - -| API Group | Resources | Permissions | -|---------------------------|--------------------------------------------------------------------------------|------------------| -| "" | configmaps, secrets, pods, services, persistent volumes, persistent volume claims | get, list, watch | -| apps | deployments, replica sets, stateful sets | get, list, watch | -| batch | jobs, cron jobs | get, list, watch | -| autoscaling | horizontal pod autoscalers | get, list, watch | -| rbac.authorization.k8s.io | roles, cluster roles, rolebindings, cluster role bindings | get, list, watch | -| networking.k8s.io | ingresses | get, list, watch | - -Weave GitOps reads basic resources so that it can monitor the effect that Flux has -on what's running. - -Reading `secrets` enables Weave GitOps to monitor the state of Helm releases -as that's where it stores the [state by default](https://helm.sh/docs/faq/changes_since_helm2/#secrets-as-the-default-storage-driver). -For clarity this these are the Helm release objects _not_ the Flux HelmRelease -resource (which are dealt with by the earlier section). - -#### Feedback from Flux - -Flux communicates the status of itself primarily via events. -These events will show when reconciliations start and stop, whether they're successful, -and information as to why they're not. - -## Recommended RBAC Configuration - -This section is purposefully vague as we intend to give a broad idea of how to implement such a system. The specifics will dependent -on your circumstances and goals. - -Our general recommendation is to use OIDC and a small number of groups that Weave GitOps can impersonate. - -Configuring Weave GitOps to impersonate Kubernetes groups rather than users has the following benefits: -* A user's permissions for impersonation by Weave GitOps can be separate from -any other permissions that they may or may not have within the cluster. -* Users do not have to be individually managed within the cluster and can have -their permissions managed together. - -### Example Setup - -Assume that your company has the following people in OIDC: -* Aisha, a cluster admin, who should have full admin access to Weave GitOps -* Brian, lead of Team-A, who should have admin permissions to their team's -namespace in Weave GitOps and read-only otherwise -* June and Jo, developers in Team-A who should have read-only access to Weave GitOps - -You can then create three groups: - -* `wego-admin` -- Bound to the `ClusterRole`, created by Helm, `wego-admin-cluster-role` -- Aisha is the only member -* `wego-team-a-admin` -- Bound to a `Role`, using the same permissions as `wego-admin-role`, created -in Team-A's namespace -- Brian and Aisha are members -* `wego-readonly` -- Bound to a `ClusterRole` that matches `wego-admin-cluster-role` but with -no `patch` permissions. -- Aisha, Brian, June and Jo are all members - -:::caution Using OIDC for cluster and Weave GitOps Authentication -If the same OIDC provider is used to authenticate a user with the cluster -itself (e.g. for use with `kubectl`) and to Weave GitOps then, depending -on OIDC configuration, they may end up with the super-set of their permissions -from Weave GitOps and any other permissions granted to them. - -This can lead to unintended consequences, like viewing `secrets`. To avoid -this, OIDC providers will often let you configure which groups are returned -to which clients. The Weave GitOps groups should not be returned to the -cluster client (and vice versa). -::: - -### Code - -The yaml to configure these permissions would look roughly like: - -
- Expand to see example RBAC - - ```yaml - # Admin cluster role - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: wego-admin-cluster-role - rules: - - apiGroups: [""] - resources: ["secrets", "pods" ] - verbs: [ "get", "list" ] - - apiGroups: ["apps"] - resources: [ "deployments", "replicasets"] - verbs: [ "get", "list" ] - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] - --- - # Read-only cluster role - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: wego-readonly-role - rules: - # All the 'patch' permissions have been removed - - apiGroups: [""] - resources: ["secrets", "pods" ] - verbs: [ "get", "list" ] - - apiGroups: ["apps"] - resources: [ "deployments", "replicasets"] - verbs: [ "get", "list" ] - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list" ] - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list" ] - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list" ] - - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] - --- - # Bind the cluster admin role to the wego-admin group - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: wego-cluster-admin - subjects: - - kind: Group - name: wego-admin # only Aisha is a member - apiGroup: rbac.authorization.k8s.io - roleRef: - kind: ClusterRole - name: wego-admin-cluster-role - apiGroup: rbac.authorization.k8s.io - --- - # Bind the admin role in the team-a namespace for the wego-team-a-admin group - apiVersion: rbac.authorization.k8s.io/v1 - kind: RoleBinding - metadata: - name: wego-team-a-admin-role - namespace: team-a - subjects: - - kind: Group - name: wego-team-a-admin # Aisha & Brian are members - apiGroup: rbac.authorization.k8s.io - roleRef: - # Use the cluster role to set rules, just bind them in the team-a namespace - kind: ClusterRole - name: wego-admin-role - apiGroup: rbac.authorization.k8s.io - --- - # Bind the read-only role to the read-only group - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: wego-readonly-role - subjects: - - kind: Group - name: wego-readonly # Everyone is a member - apiGroup: rbac.authorization.k8s.io - roleRef: - kind: ClusterRole - name: wego-readonly-role - apiGroup: rbac.authorization.k8s.io - --- - ``` - -
- - - -### TLS Configuration - -By default, the WGE UI pod will listen on port `8000` with TLS enabled. -WGE will generate and use a self-signed certificate for this purpose. - -It can then be accessed via port-forwarding: - -`kubectl port-forward --namespace flux-system svc/clusters-service 8000:8000` - -If you're using an ingress controller to terminate TLS you can disable it in the Helm release: - -```yaml - values: - tls: - enabled: false -``` - -Other ingress configuration changes can be made via the ingress configuration - -```yaml - values: - ingress: - enabled: true - ... other parameters specific to the ingress type ... -``` - -### Cluster User - -#### Updating the Cluster User - -To change either the username or the password, recreate the `cluster-user-auth` -with the new details. - -Only one Cluster User can be created this way. To add more users, enable an OIDC provider. - -#### Remove Cluster User Authentication - -To remove the Cluster User as a login method, set the following values in the -[Helm Chart](../../references/helm-reference.md): - -```yaml -# -adminUser: - create: false -# -additionalArgs: -- --auth-methods=oidc -# -``` -:::caution If you are disabling an already existing Cluster User - -If you are disabling an already existing Cluster User, you will need to -manually delete the Kubernetes Secret and any User Roles that were created on -the cluster. - -::: - - -### OIDC - -#### Customization - -For some OIDC configurations, you may need to customise the requested [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) or [claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims). - -The `oidcUsernamePrefix` and `oidcGroupsPrefix` work in the same way as the Kubernetes [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) command-line options, if you need them for Kubernetes, you will likely need them here. - -#### Scopes - -By default, the following scopes are requested: "openid","offline_access","email","groups". - -The "openid" scope is **mandatory** for OpenID auth and will be added if not provided. The "email" and "groups" scopes are commonly used as unique identifiers in organisations. - -"offline_access" allows us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid. You can, however, change the defaults. -```sh -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL=$oidc-issuer-url \ - --from-literal=clientID=$client-id \ - --from-literal=clientSecret=$client-secret \ - --from-literal=redirectURL=redirect-url \ - --from-literal=tokenDuration=token-duration \ - --from-literal=customScopes=custom,scopes -``` -The format for the `customScopes` key is a comma-separated list of scopes to request. In this case, "custom", "scopes", and "openid" would be requested. - -#### Claims - -By default, the following claims are parsed from the OpenID [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken) "email" and "groups". These are presented as the `user` and `groups` when WGE communicates with your Kubernetes API server. - -This is equivalent to [configuring](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server) your `kube-apiserver` with `--oidc-username-claim=email --oidc-groups-claim=groups`. - -Again, you can configure these from the `oidc-auth` `Secret`. - -```sh -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL=oidc-issuer-url \ - --from-literal=clientID=client-id \ - --from-literal=clientSecret=client-secret \ - --from-literal=redirectURL=redirect-url \ - --from-literal=tokenDuration=token-duration \ - --from-literal=claimUsername=sub \ - --from-literal=claimGroups=groups -``` -There are two separate configuration keys. You can override them separately. They should match your `kube-apiserver` configuration. - -### Customise the UI - -#### Login - -The label of the OIDC button on the login screen is configurable via a feature flag environment variable. -This can give your users a more familiar experience when logging in. - -Adjust the configuration in the Helm `values.yaml` file or the `spec.values` section of the Weave GitOps `HelmRelease` resource: - -```yaml -extraEnvVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` - -### Install Other Components - -#### Cluster Management via CAPI - -TBA - -#### Policy via Weave Policy Agent - -To install [Policy Agent](../../policy/intro.mdx) follow any of the following approaches: - - - - -You could configure this stage by using the following flags and examples: - -```bash - # install Policy Agent alongside Weave GitOps Enterprise - gitops bootstrap --components-extra="policy-agent" -``` - -For more information about the CLI configurations, check the below sections [here](#cli-configurations) - - - -[Policy agent](../../policy/intro.mdx) comes packaged with the WGE chart. To install it, set the following values: - -- `values.policy-agent.enabled`: set to true to install the agent with WGE -- `values.policy-agent.config.accountId`: organization name, used as identifier -- `values.policy-agent.config.clusterId`: unique identifier for the cluster - -Commit and push all the files - -```bash -git add clusters/management/weave-gitops-enterprise.yaml -git commit -m "Deploy Weave GitOps Enterprise" -git push -``` - -Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the `flux-system` namespace to verify all pods are running. - - - - -#### Infrastructure via Tf-Controller - -// TBA - - -### Configure Write Access to Git - -Weave GitOps Enterprise creates pull requests for adding resources. To do this, it needs to be able to write to the Git repository. -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 `$WGE_DASHBOARD_URL/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 `$WGE_DASHBOARD_URL/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='App ID value'" \ - --from-literal="AZURE_DEVOPS_CLIENT_SECRET='Client Secret value'" -``` - -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. - - - - +## Access the dashboard -## Next Steps - -Here are a couple of options for you to take your next steps with WGE. Explore one option or all of them, in no particular order. - -- [Cluster Management](https://docs.gitops.weave.works/docs/next/cluster-management/intro/): We'll show you how to join WGE to a cluster and install an application on that cluster *without* using Cluster API. But if you prefer using Cluster API, our docs cover that too. -- Install the [Terraform Controller](https://weaveworks.github.io/tf-controller/) to reconcile your Terraform resources in a GitOps way. With Flux and the TF Controller, WGE makes it easy to add Terraform templates to your clusters and continuously reconcile any changes made to the Terraform source manifest. -- Install [Policy agent](../../policy/intro.mdx), which comes packaged with the WGE chart. - -## Further Reference - -### CLI - -- `--kubeconfig` Paths to a kubeconfig. Only required if out-of-cluster. -- `--bootstrap-flux` chose whether you want to install flux in the generic way in case no flux installation detected -- `-b`, `--branch` git branch for your flux repository (example: main) -- `-i`, `--client-id` OIDC client ID -- `--client-secret` OIDC client secret -- `--components-extra` extra components to be installed from (policy-agent, tf-controller) -- `--discovery-url` OIDC discovery URL -- `--export` write to stdout the bootstrapping manifests without writing in the cluster or Git. It requires Flux to be bootstrapped. -- `--git-password` git password/token used in https authentication type -- `--git-username` git username used in https authentication type -- `-h`, `--help` help for bootstrap -- `-k`, `--private-key` private key path. This key will be used to push the Weave GitOps Enterprise's resources to the default cluster repository -- `-c`, `--private-key-password` private key password. If the private key is encrypted using password -- `-r`, `--repo-path` git path for your flux repository (example: clusters/my-cluster) -- `--repo-url` Git repo URL for your Flux repository. For supported URL examples see [here](https://fluxcd.io/flux/cmd/flux_bootstrap_git/) -- `-s`, `--silent` chose the defaults with current provided information without asking any questions -- `-v`, `--version` version of Weave GitOps Enterprise (should be from the latest 3 versions) -- `-p`, `--password` The Weave GitOps Enterprise password for dashboard access \ No newline at end of file +Continue the main flow to [access the dashboard](../install-enterprise-getting-started/#access-the-dashboard) \ No newline at end of file diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx index 8539e32383..f1789f551b 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx @@ -1,6 +1,7 @@ --- title: Step 1 - Getting Started hide_title: true +pagination_prev: enterprise/getting-started/intro-enterprise pagination_next: enterprise/getting-started/install-enterprise-onboard-platform-engineers toc_max_heading_level: 4 --- @@ -92,7 +93,9 @@ Exectue the workflow using the method below that better match your expectations. # Run the command to follow the interactive session. gitops bootstrap ``` - +- For more information about the CLI configurations, check the below sections [here](#cli-configurations) +- For more information about what is happening under the hoods, see [Manual Bootstrapping](../install-enterprise-getting-started-manual) + @@ -116,7 +119,8 @@ gitops bootstrap --silent \ --private-key-path="private-key-path" --private-key-password="private-key-password" ``` -For more information about the CLI configurations, check the below sections [here](#cli-configurations) +- For more information about the CLI configurations, check the below sections [here](#cli-configurations) +- For more information about what is happening under the hoods, see [Manual Bootstrapping](../install-enterprise-getting-started-manual) diff --git a/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx b/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx index 1e69e2ff8f..47218cdb90 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx @@ -27,37 +27,17 @@ The bootstrapping workflow has the following stages: ## Bootstrap Flux -This stage is about bootstrapping Fux which involves deploying Flux into the management cluster and configure it to reconcile your Git repository. +No additional topics required for this stage. -The `flux bootstrap` command enables you to deploy Flux on a cluster the GitOps way. See the different -option [Flux bootstrap](https://fluxcd.io/docs/cmd/flux_bootstrap/) documentation. - -Two examples using [`flux bootstrap git`](https://fluxcd.io/flux/cmd/flux_bootstrap_git/) are: - -```bash -# Run bootstrap for a Git repository and authenticate using a password -flux bootstrap git --url="https://example.com/repository.git" --"password=password" --path="clusters/my-cluster" - -# Run bootstrap for a Git repository with a private key and password -flux bootstrap git --url="ssh://git@example.com/repository.git" --private-key-file="path/to/private.key" --password="password" --path="clusters/my-cluster" -``` ### Entitlements -Weave GitOps Enterprise Entitlement is your obtained license to use our product. The Entitlements file is a Kubernetes secret that contains your licence. -To get the entitlement secret please contact *sales@weave.works*, then apply it on your management cluster with the name `weave-gitops-enterprise-credentials` under `flux-system` namespace. +No additional topics required for this stage. -```bash - kubectl apply -n flux-system -f entitlements.yaml -``` - -:::info Verify Entitlements +### Authentication -The following verification is done when bootstrapping using the CLI: -- The secret exists on the management cluster -- It has a valid content -- Entitlement is not expired +#### Authentication via OIDC -::: +Before onboarding other users to latfo ### Authentication @@ -195,47 +175,6 @@ CLI does not support Authorization yet. It should be hadled as part of https://g ::: - -Weave GitOps Enterprise HelmRelease installed with the defaults values that allows `wego-admin` user to have high privileges, -so you could temporarily manage the aspect of bootstrapping with smaller friction: - -It creates a set of `ClusterRoleBinding` that allow `cluster-admin` access to the resources in the cluster. - -```bash -kubectl get clusterrolebindings.rbac.authorization.k8s.io |grep wego-admin - -wego-admin-gitops-capi-cluster-reader ClusterRole/gitops-capicluster-reader 20d -wego-admin-read-apps ClusterRole/gitops-apps-reader 20d -wego-admin-read-automatedclusterdiscoveries ClusterRole/gitops-automatedclusterdiscoveries-reader 20d -wego-admin-read-canaries ClusterRole/gitops-canaries-reader 20d -wego-admin-read-cluster-secrets ClusterRole/gitops-secrets-reader 20d -wego-admin-read-external-secrets ClusterRole/gitops-external-secrets-reader 20d -wego-admin-read-gitopsclusters ClusterRole/gitops-gitopsclusters-reader 20d -wego-admin-read-identities ClusterRole/gitops-identities-reader 20d -wego-admin-read-pipelines ClusterRole/gitops-pipelines-reader 20d -wego-admin-read-policies ClusterRole/gitops-policies-reader 20d -wego-admin-read-templates ClusterRole/gitops-templates-reader 20d -wego-admin-read-workspaces ClusterRole/gitops-workspaces-reader 20d -``` -// TODO add me explorer access rules debug view - -It creates a `RoleBinding` that allow `admin` access secrets in `flux-system` namespace: - -```bash -kubectl get -A rolebindings.rbac.authorization.k8s.io |grep wego-admin - -flux-system wego-admin-read-release-namespace-secrets ClusterRole/gitops-secrets-reader 20d -``` - -:::caution Flux and Weave GitOps trust -We currently assume fully trusted security context at the level of flux-system namespace. This represents a challenge -in terms of least-privilege access to be tackled as part of https://github.com/weaveworks/weave-gitops/issues/4036 -::: - -// TODO add me explorer access rules debug view - -See how to harden this section in [Day 1 Cluster User](#cluster-user). - OIDC is highly context dependent, during bootstrapping no RBAC resources are created but expected to exist @@ -268,8 +207,6 @@ spec: Save these two files in your Git repository, then commit and push. Flux will deploy the kustomization and the RBAC resources will be created. -See how to harden this section in [Day 1](#oidc-authorization). - diff --git a/website/sidebars.js b/website/sidebars.js index ac77f37a3f..26b03f9801 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -39,7 +39,17 @@ module.exports = { id: "enterprise/getting-started/intro-enterprise", }, items: [ - "enterprise/getting-started/install-enterprise-getting-started", + { + type: "category", + label: "Step 1 - Getting Started", + link: { + type: "doc", + id: "enterprise/getting-started/install-enterprise-getting-started", + }, + items: [ + "enterprise/getting-started/install-enterprise-getting-started-manual", + ], + }, "enterprise/getting-started/install-enterprise-onboard-platform-engineers", "enterprise/getting-started/releases-enterprise", {