From 3ad07720273f21ffac3f113c640c350d841111c7 Mon Sep 17 00:00:00 2001 From: Lauri Date: Mon, 7 Aug 2023 12:46:51 +0200 Subject: [PATCH 01/20] Update airgap install page with small fixes --- .../install-enterprise-airgap.mdx | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise-airgap.mdx b/website/docs/enterprise/getting-started/install-enterprise-airgap.mdx index 2fc25470cf..62942d9b1f 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-airgap.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-airgap.mdx @@ -13,12 +13,12 @@ From [wikipedia](https://en.wikipedia.org/wiki/Air_gap_(networking)) >An air gap, air wall, air gapping or disconnected network is a network security measure employed on one or more computers to ensure that a secure computer network is physically isolated from unsecured networks, such as the public Internet or an unsecured local area network... -This document guides on how to install Weave Gitops Enterprise in a restricted environment. +This document guides on how to install Weave GitOps Enterprise (WGE) in a restricted environment. # Before You Start There are multiple restrictions that could happen within an air-gapped environment. This guide assumes that you have egress network -restrictions. In order to install Weave Gitops Enterprise (WGE), the required artifacts are required to be loaded +restrictions. In order to install WGE, the required artifacts must be loaded from a private registry. This guide helps you with the task to identity the Helm charts and container images required to install WGE and to load them into your private registry. @@ -33,25 +33,25 @@ to load the artifacts in the private network. Finally, we aim to provide an end to end example to use it as a guidance more than a recipe. Feel free to adapt the details that do not fit within your context. -# Install +# Install WGE There are different variations of the following stages and conditions. We consider that installing WGE in an air-gapped environment could follow the following stages. -1. Setup a WGE install environment. +1. Set up a WGE install environment. 2. Collect artifacts and publish to a private registry. -3. Install Weave Gitops Enterprise in the air-gapped environment. +3. Install WGE in the air-gapped environment. -## Setup a WGE install environment +## Set up a WGE install environment -The main goal of this stage is to recreate a local Weave Gitops Enterprise within your context, to collect +The main goal of this stage is to recreate a local WGE within your context, to collect the container images and Helm charts, that will be required in your private registry for the offline installation. A three-step setup is followed. 1. Setup a proxy host 2. Setup a private registry -3. Install Weave Gitops Enterprise +3. Install WGE ### Setup a proxy host @@ -143,7 +143,7 @@ helm repo update private At this stage you have already a private registry for container images and helm charts. -### Install Weave Gitops Enterprise +### Install WGE This step is to gather the artifacts and images in your local environment to push to the private registry. @@ -274,7 +274,7 @@ spec: -#### Weave Gitops Enterprise +#### WGE Update the following manifest to your context. @@ -482,7 +482,7 @@ ghcr.io/weaveworks-liquidmetal/flintlock-kernel:5.10.77 ## Airgap Install -### Weave Gitops Enterprise +### Weave GitOps Enterprise At this stage you have in your private registry both the Helm charts and container images required to install Weave GitOps Enterprise. Now you are ready to install WGE from your private registry. From 66b0fda9c2e45c2fc18f0e4f3f94905d00085f44 Mon Sep 17 00:00:00 2001 From: Lauri Date: Mon, 7 Aug 2023 12:47:10 +0200 Subject: [PATCH 02/20] Update install wge page --- .../getting-started/install-enterprise.mdx | 978 ++++++++++++++++-- 1 file changed, 885 insertions(+), 93 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index da4c3a9223..b773e00e44 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -31,70 +31,52 @@ import TOCInline from "@theme/TOCInline"; There is no need to install the open source version of Weave GitOps before installing Weave GitOps Enterprise. ::: -## Example: Set up a Management Cluster with CAPA and EKS +## Prerequisites -To get you started, we'll cover EKS as our management cluster with the CAPA provider. Please note again that Weave GitOps Enterprise supports [clusters without Cluster API](../../cluster-management/managing-clusters-without-capi.mdx), as well as any combination of management cluster and CAPI provider. +To get up and running with Weave GitOps Enterprise: +- install Weave GitOps Enterprise, using the `gitops-ee bootstrap` command +- create a Kubernetes cluster +- add your cluster to kubeconfig—which you'll get from Kubernetes—so that the kubeconfig correctly points to the management cluster +- create a Git repository; in the instructions below, we refer to a `fleet-infra` repository +- configure your Git client 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)) +- obtain a valid entitlement secret from Weaveworks and apply it to your cluster +- install a compatible version of Flux onto your cluster; see below for how-to guidance -### Prep Step: Create a Repository -Create a new private GitHub repository and give it a name. We'll call our repo `fleet-infra`. - -Set up a Git client for your private repo. For GitHub, see 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 [setting 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). - -[Cluster API](https://cluster-api.sigs.k8s.io/introduction.html) provides declarative APIs, controllers, and tooling to manage the lifecycle of Kubernetes clusters, across a large number of [infrastructure providers](https://cluster-api.sigs.k8s.io/reference/providers.html#infrastructure). -The CAPI custom resource definitions are platform-independent as each provider implementation handles the creation of virtual machines, -VPCs, networks, and other required infrastructure parts, enabling consistent and repeatable cluster deployments. - -The following example and steps reflect Flux’s architecture and operations. Go [here](https://fluxcd.io/docs/cmd/) for more detailed documentation about Flux. - -### 1. CAPA Setup - -Cluster API requires kubectl access to an existing Kubernetes cluster. For this example, configure kubectl to use the management cluster: +As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster: ```bash -export KUBECONFIG=/path/to/kubeconfig +kubectl apply -f entitlements.yaml ``` -After having configured kubectl, deploy the CAPA components by following the [steps provided by Cluster API documentation](https://cluster-api-aws.sigs.k8s.io/getting-started.html#install-clusterctl). - -### 2. Prepare IAM for Installation - -Cluster API needs special permissions in AWS. Use the `clusterawsadm` command below to roll out a CloudStack and install the permissions into your AWS account. Although the CloudStack is bound to a region, the resulting permissions are globally scoped. You can use any AWS Region that you have access to. +### Install the Weave GitOps Enterprise CLI Tool -The `clusterawsadm` command takes an AWSIAMConfiguration file. [Cluster API docs provide the command](https://cluster-api-aws.sigs.k8s.io/topics/using-clusterawsadm-to-fulfill-prerequisites.html#with-eks-support) for you; run this. +To do this, you can use either brew or curl. -Run the `clusterawsadm` command to create an IAM group: + + ```bash -clusterawsadm bootstrap iam create-cloudformation-stack --config eks-config.yaml --region $REGION +brew install weaveworks/tap/gitops-ee ``` -Create an IAM User, which will be used as a kind of service account, and assign the newly created group to this user. The group name will be something like: `cluster-api-provider-aws-s-AWSIAMGroupBootstrapper-XXXX`. - -Create a secret for the newly created IAM user. - -### 3. Create the Cluster + -In testing, we used the following values: -`$INSTANCESIZE` : t3.large -`$NUMOFNODES` : 2 -`$MINNODES` : 2 -`$MAXNODES` : 6 + ```bash -eksctl create cluster -n "$CLUSTERNAME" -r "$REGION" --nodegroup-name workers -t $INSTANCESIZE --nodes $NUMOFNODES --nodes-min $MINNODES --nodes-max $MAXNODES --ssh-access --alb-ingress-access +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 ``` -### 4. Add the Cluster to kubeconfig - -Once you've created your cluster, add it to your `kubeconfig`: - -```bash -aws eks --region "$REGION" update-kubeconfig --name "$CLUSTERNAME" -``` + + -### 5. Install Flux Onto Your Cluster with the `flux bootstrap` Command +### Install Flux Onto Your Cluster with the `flux bootstrap` Command -The `flux bootstrap` command enables you to deploy Flux on a cluster the GitOps way. Go [here](https://fluxcd.io/docs/cmd/) for more information about the `flux bootstrap` command. +The `flux bootstrap` command enables you to deploy Flux on a cluster the GitOps way. Go [here](https://fluxcd.io/docs/cmd/) for more information about the command. @@ -137,33 +119,828 @@ Your private GitHub repo should have a clusters/management folder that includes At this point your Flux management cluster should be running. Take a look at the repository you created earlier. -### 6. Install CAPA +## Set up Authentication and RBAC + +### Securing Access to the Dashboard + +There are two supported methods for logging in to the dashboard, that work with standard Kubernetes RBAC: +- Login via an OIDC provider: recommended, as this will allow 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). +- Login via a cluster user account: which is insecure, and which we only recommend for local and 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. + +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. + + + + +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" | + +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: + +```sh +kubectl create secret generic oidc-auth \ + --namespace flux-system \ + --from-literal=issuerURL= \ + --from-literal=clientID= \ + --from-literal=clientSecret= \ + --from-literal=redirectURL= \ + --from-literal=tokenDuration= +``` + +Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identities will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly, but we recommend reading the [service account](#gitops-dashboard-service-account-permissions) and [user permissions](#user-permissions) pages to understand which actions are needed for Weave GitOps to function correctly. + +### 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). + +#### Scopes + +By default, the following scopes are requested: "openid","offline_access","email","groups". + +The "openid" scope is **mandatory** for OpenID auth. 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= \ + --from-literal=clientID= \ + --from-literal=clientSecret= \ + --from-literal=redirectURL= \ + --from-literal=tokenDuration= \ + --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`. -You do not need to install a CAPI provider to provision Kubernetes clusters using Weave GitOps Enterprise—you can also provision with Terraform. But for this example with CAPA, you must. +Again, you can configure these from the `oidc-auth` `Secret`. + +```sh +kubectl create secret generic oidc-auth \ + --namespace flux-system \ + --from-literal=issuerURL= \ + --from-literal=clientID= \ + --from-literal=clientSecret= \ + --from-literal=redirectURL= \ + --from-literal=tokenDuration= \ + --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. + + -Download a specific version of clusterctl from the [releases page](https://github.com/kubernetes-sigs/cluster-api/releases). We've tested the example templates provided in this guide with `clusterctl` version `1.1.3`. + -Next, run this command: +### Configuring OIDC with Dex and GitHub +This example uses [Dex](https://dexidp.io/) and its [GitHub connector](https://dexidp.io/docs/connectors/github/) to show you how to log in to the Weave GitOps dashboard by authenticating with your GitHub account. It assumes you have already installed Weave GitOps on a Kubernetes cluster, per the instructions above, and have also [enabled TLS](#tls-configuration). + +Dex is an identity service that uses [OpenID Connect](https://openid.net/connect/) to +drive authentication for other apps. There are other solutions for identity and access management, such as [Keycloak](https://www.keycloak.org/). + +Create a namespace where you will install Dex: + +```yaml +--- +apiVersion: v1 +kind: Namespace +metadata: + name: dex +``` + +Get a GitHub ClientID and Client secret by creating a [new OAuth application](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). + +![GitHub OAuth configuration](/img/enterprise/getting-started/install-enterprise/github-oauth-application.png) ```bash -export EXP_EKS=true -export EXP_MACHINE_POOL=true -export CAPA_EKS_IAM=true -export EXP_CLUSTER_RESOURCE_SET=true +kubectl create secret generic github-client \ + --namespace=dex \ + --from-literal=client-id=${GITHUB_CLIENT_ID} \ + --from-literal=client-secret=${GITHUB_CLIENT_SECRET} +``` -clusterctl init --infrastructure aws +### Deploy Dex + +Use `HelmRepository` and `HelmRelease` objects to let Flux deploy everything. + +
Expand to see resource manifests + +```yaml +--- +apiVersion: source.toolkit.fluxcd.io/v1beta1 +kind: HelmRepository +metadata: + name: dex + namespace: dex +spec: + interval: 1m + url: https://charts.dexidp.io +--- +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: dex + namespace: dex +spec: + interval: 5m + chart: + spec: + chart: dex + version: 0.6.5 + sourceRef: + kind: HelmRepository + name: dex + namespace: dex + interval: 1m + values: + image: + tag: v2.31.0 + envVars: + - name: GITHUB_CLIENT_ID + valueFrom: + secretKeyRef: + name: github-client + key: client-id + - name: GITHUB_CLIENT_SECRET + valueFrom: + secretKeyRef: + name: github-client + key: client-secret + config: + # Set it to a valid URL + issuer: https://dex.dev.example.tld + + # See https://dexidp.io/docs/storage/ for more options + storage: + type: memory + + staticClients: + - name: 'Weave GitOps Core' + id: weave-gitops + secret: AiAImuXKhoI5ApvKWF988txjZ+6rG3S7o6X5En + redirectURIs: + - 'https://localhost:9001/oauth2/callback' + - 'https://0.0.0.0:9001/oauth2/callback' + - 'http://0.0.0.0:9001/oauth2/callback' + - 'http://localhost:4567/oauth2/callback' + - 'https://localhost:4567/oauth2/callback' + - 'http://localhost:3000/oauth2/callback' + + connectors: + - type: github + id: github + name: GitHub + config: + clientID: $GITHUB_CLIENT_ID + clientSecret: $GITHUB_CLIENT_SECRET + redirectURI: https://dex.dev.example.tld/callback + orgs: + - name: weaveworks + teams: + - team-a + - team-b + - QA + - name: ww-test-org + ingress: + enabled: true + className: nginx + annotations: + cert-manager.io/cluster-issuer: letsencrypt-prod + hosts: + - host: dex.dev.example.tld + paths: + - path: / + pathType: ImplementationSpecific + tls: + - hosts: + - dex.dev.example.tld + secretName: dex-dev-example-tld ``` -Please note that, while the next few steps apply to our example, they are also relevant whether you're using another CAPI provider or none at all. +
-## Apply the Entitlements Secret +An important part of the configuration is the `orgs` field on the GitHub +connector, which allows you to define groups within a GitHub organisation: -Contact sales@weave.works for a valid entitlements secret. Then apply it to the cluster: +```yaml +orgs: +- name: weaveworks + teams: + - team-a + - team-b + - QA +``` + +In this example, the GitHub organisation is `weaveworks` and all members of the `team-a`, +`team-b`, and `QA` teams can authenticate. Group membership is added to +the user. + +Based on these groups, we can bind roles to groups: + +
Expand to see group role bindings + +```yaml +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: wego-test-user-read-resources + namespace: flux-system +subjects: + - kind: Group + name: weaveworks:QA + namespace: flux-system +roleRef: + kind: Role + name: wego-admin-role + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: wego-admin-role + namespace: flux-system +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"] +``` + +
+ +In the same way, we can bind cluster roles to a group: + +
Expand to see group cluster role bindings + +```yaml +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: weaveworks:team-a +subjects: +- kind: Group + name: weaveworks:team-a + apiGroup: rbac.authorization.k8s.io +roleRef: + kind: ClusterRole + name: cluster-admin + apiGroup: rbac.authorization.k8s.io +``` + +
+ +### Set up a Static User + +For a static user, add `staticPasswords` to the `config`: + +```yaml +spec: + values: + config: + staticPasswords: + - email: "admin@example.tld" + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: "admin" + userID: "08a8684b-db88-4b73-90a9-3cd1661f5466" +``` + +Generate a static user password via the `gitops` CLI: ```bash -kubectl apply -f entitlements.yaml +PASSWORD="" +echo -n $PASSWORD | gitops get bcrypt-hash +$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q +``` + +### OIDC Login + +Using the "Login with OIDC Provider" button: + +![Login page](/img/enterprise/getting-started/install-enterprise/oidc-login.png) + +We have to authorize the GitHub OAuth application: + +![GitHub OAuth page](/img/enterprise/getting-started/install-enterprise/github-auth.png) + +After that, grant access to Dex: + +![Dex grant access](/img/enterprise/getting-started/install-enterprise/dex-auth.png) + +Now we are logged in with our GitHub user and can see all of the resources we have +access to: + +![UI logged in](/img/enterprise/getting-started/install-enterprise/ui-logged-in.png) + + + + + +:::danger Important +This is an **insecure** method of securing your dashboard which we only recommend for local +and development environments, or if you need to activate emergency access to a damaged cluster. + +Note also that this mechanism only exists for a single user. You will not be able to create multiple users. Weave GitOps does not provide its own authentication mechanism. For secure and fully-featured authentication we **strongly recommend** using an OIDC provider, as described in the other tab. +::: + +### Configuring the Emergency User + +Before you log in via the emergency 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: + +```sh +PASSWORD="" +echo -n $PASSWORD | gitops get bcrypt-hash +$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q +``` + +Now create a Kubernetes secret to store your chosen username and the password hash: + +```sh +kubectl create secret generic cluster-user-auth \ + --namespace flux-system \ + --from-literal=username=admin \ + --from-literal=password='$2a$10$OS5NJmPNEb13UTOSKngMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q' +``` + +You should now be able to login via the cluster user account using your chosen username and password. + +### Updating the Emergency User + +To change either the username or the password, recreate the `cluster-user-auth` +with the new details. + +Only one emergency user can be created this way. To add more users, enable an OIDC provider. + +### User Permissions + +By default, both a ClusterRole and Role are generated for the emergency 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 emergency 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. + +:::tip +To remove the emergency 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 +# +``` + +If you are disabling an already existing emergency user, you will need to +manually delete the Kubernetes Secret and any User Roles that were created on +the cluster. +::: + + + + +### GitOps Dashboard Service Account Permissions + +This section covers the service account [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +for the Weave GitOps application, which the WGE UI requires to work. The default permissions are defined in the [Helm chart](https://github.com/weaveworks/weave-gitops/tree/main/charts/gitops-server/templates/role.yaml), which will generate a cluster role with the following permissions: + +```yaml +rules: +# Used to query the cluster +- apiGroups: [""] + resources: ["users", "groups"] # set by rbac.impersonationResources + verbs: [ "impersonate" ] + # resourceNames: [] # set by rbac.impersonationResourceNames +# Used to get OIDC/static user credentials for login +- apiGroups: [""] + resources: [ "secrets" ] + verbs: [ "get", "list" ] + resourceNames: # set by rbac.viewSecretsResourceNames + - "cluster-user-auth" + - "oidc-auth" +# The service account needs to read namespaces to know where it can query +- 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)) + +### The Helm Values + +| Value | Description | Default | +|-----------------------------------|---------------------------------------------------------------------|--------------------------------------| +| `rbac.impersonationResources` | Which resource types the service account can impersonate | `["users", "groups"]` | +| `rbac.impersonationResourceNames` | Specific users, groups or services account that can be impersonated | `[]` | +| `rbac.viewSecretsResourceNames` | Specific secrets that can be read | `["cluster-user-auth", "oidc-auth"]` | + + +### 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](../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. + +### Configuring Impersonation + +We highly recommend limiting which users and groups the +application can impersonate by setting `rbac.impersonationResourceNames` in +the Helm chart's `values`. e.g.: + +```yaml +rbac: + impersonationResources: ["groups"] + impersonationResourceNames: + - admin + - dev-team + - qa-team +``` +In this example, the application can only impersonate the group's admin, dev-team, +and qa-team. This also implicitly disables the [emergency cluster user](../emergency-user)). + +Unfortunately, not all OIDC providers support groups. You may need to +manually enumerate users—for example: + +```yaml +rbac: + impersonationResources: ["users"] + impersonationResourceNames: + - aisha@example.com + - bill@example.com + - wego-admin # enable the emergency cluster user +``` + +A better, albeit more involved, solution is to set up an OIDC connector like Dex and use that to manage groups for you. + +### 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](../emergency-user), and the latter holds OIDC configuration. + +The application needs to be able to access these secrets in order to +authenticate users. + +#### Configuring Secrets + +The `rbac.viewSecretsResourceNames` value allows the operator to change which secrets the +application can read. This is mostly so that the secret can be removed if the emergency user is not +configured, or if the secret _is_ in use but renamed. + +### 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. + +#### 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. + +### Login UI + +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" +``` + +## 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 + +The Weave GitOps service account can then be configured with: +```yaml +rbac: + impersonationResourceNames: ["wego-admin", "wego-team-a-admin", "wego-readonly"] + impersonationResources: ["groups"] +``` + +so that only these three groups can be `impersonated` by the service account. + +:::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 +--- +``` + +
+ ## Configure Access for Writing to Git from the Weave GitOps Enterprise UI Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps. @@ -285,6 +1062,45 @@ WGE is now configured to ask users for authorization the next time a pull reques +## TLS Configuration + +By default, the dashboard will listen on 0.0.0.0:9001 with TLS disabled and +without exposing any external connection. + +We don't recommend exposing services without TLS. Without a certificate, you +can't be sure if you're using the correct service, and the traffic will be easily +monitored—or even tampered with. All communication between the user and an endpoint +with TLS will be encrypted. + +To expose an external connection, you must first configure TLS. TLS termination +can be provided via an ingress controller or directly by the dashboard. In +either case, the Helm Release must be updated. To have the dashboard itself +handle TLS, you must create a `tls` secret containing the cert and key: + +```cli +kubectl create secret tls my-tls-secret \ + --cert=path/to/cert/file \ + --key=path/to/key/file +``` + +and reference it from the Helm release: + +```yaml + values: + serverTLS: + enabled: true + secretName: "my-tls-secret" +``` + +If you prefer to delegate TLS handling to the ingress controller instead, your +helm release should look like: + +```yaml + values: + ingress: + enabled: true + ... other parameters specific to the ingress type ... +``` ## Configure Helm Chart and Commit @@ -328,24 +1144,6 @@ The other important path to configure is where you'll store applications and wor By default this is `./clusters`. When a new cluster is specified, any selected profiles will be written to `./clusters/{.namespace}/{.clusterName}/profiles.yaml`. When the new cluster is bootstrapped, Flux will sync the `./clusters/{.namespace}/{.clusterName}` path. -#### (Optional) Install policy agent - -[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. - ## Configure Your Password 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 CLI. @@ -361,29 +1159,23 @@ A validation to know it’s working: kubectl get secret -n flux-system cluster-user-auth ``` -## Install the Weave GitOps Enterprise CLI Tool - -To do this, you can use either brew or curl. +### (Optional) Install Policy Agent - - - -```bash -brew install weaveworks/tap/gitops-ee -``` +[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 -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 +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. ## Next Steps @@ -391,4 +1183,4 @@ Here are a couple of options for you to take your next steps with WGE. Explore o - [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. +- Install [Policy agent](../../policy/intro.mdx), which comes packaged with the WGE chart. \ No newline at end of file From 3ff6132600b4a250c7f6679fa48ec8b05b71babd Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Tue, 8 Aug 2023 17:34:31 +0200 Subject: [PATCH 03/20] Update website/docs/enterprise/getting-started/install-enterprise.mdx Co-authored-by: Himangini --- website/docs/enterprise/getting-started/install-enterprise.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index b773e00e44..3777de3123 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -551,7 +551,7 @@ Follow the instructions in the next section in order to configure RBAC correctly :::tip To remove the emergency user as a login method, set the following values in the -[Helm Chart](../references/helm-reference.md): +[Helm Chart](../../references/helm-reference.md): ```yaml # From 6bbdf6f6f900ed15ef2ba08c2e693b0c8a994300 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Wed, 9 Aug 2023 15:56:44 +0200 Subject: [PATCH 04/20] Update website/docs/enterprise/getting-started/install-enterprise.mdx Co-authored-by: Max Jonas Werner --- website/docs/enterprise/getting-started/install-enterprise.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 3777de3123..80c6e4e34d 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -66,7 +66,8 @@ 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 +export VERSION= +curl --silent --location "https://artifacts.wge.dev.weave.works/releases/bin/${VERSION}/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp sudo mv /tmp/gitops /usr/local/bin gitops version ``` From 171c1f5b4a15fe2bfb682b2b995258ec24f5f8ee Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Wed, 9 Aug 2023 16:29:30 +0200 Subject: [PATCH 05/20] Update install-enterprise.mdx Reverse order of two prereqs --- .../docs/enterprise/getting-started/install-enterprise.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 80c6e4e34d..311724abc5 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -34,8 +34,8 @@ There is no need to install the open source version of Weave GitOps before insta ## Prerequisites To get up and running with Weave GitOps Enterprise: -- install Weave GitOps Enterprise, using the `gitops-ee bootstrap` command - create a Kubernetes cluster +- install Weave GitOps Enterprise, using the `gitops-ee bootstrap` command - add your cluster to kubeconfig—which you'll get from Kubernetes—so that the kubeconfig correctly points to the management cluster - create a Git repository; in the instructions below, we refer to a `fleet-infra` repository - configure your Git client properly (if using GitHub, for example, @@ -1184,4 +1184,4 @@ Here are a couple of options for you to take your next steps with WGE. Explore o - [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. \ No newline at end of file +- Install [Policy agent](../../policy/intro.mdx), which comes packaged with the WGE chart. From 2aea43d61617dede542495a0b83910d857a791a8 Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Wed, 9 Aug 2023 18:02:19 +0200 Subject: [PATCH 06/20] Fix up image refs --- .../enterprise/getting-started/install-enterprise.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 311724abc5..f9c4627026 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -229,7 +229,7 @@ metadata: Get a GitHub ClientID and Client secret by creating a [new OAuth application](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). -![GitHub OAuth configuration](/img/enterprise/getting-started/install-enterprise/github-oauth-application.png) +![GitHub OAuth configuration](/img/guides/setting-up-dex/github-oauth-application.png) ```bash kubectl create secret generic github-client \ @@ -451,20 +451,20 @@ $2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q Using the "Login with OIDC Provider" button: -![Login page](/img/enterprise/getting-started/install-enterprise/oidc-login.png) +![Login page](/img/guides/setting-up-dex/oidc-login.png) We have to authorize the GitHub OAuth application: -![GitHub OAuth page](/img/enterprise/getting-started/install-enterprise/github-auth.png) +![GitHub OAuth page](/img/guides/setting-up-dex/github-auth.png) After that, grant access to Dex: -![Dex grant access](/img/enterprise/getting-started/install-enterprise/dex-auth.png) +![Dex grant access](/img/guides/setting-up-dex/dex-auth.png) Now we are logged in with our GitHub user and can see all of the resources we have access to: -![UI logged in](/img/enterprise/getting-started/install-enterprise/ui-logged-in.png) +![UI logged in](/img/guides/setting-up-dex/ui-logged-in.png) From 47abc2a82c0798fa724b67a83cb81c6aef06c11c Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Thu, 10 Aug 2023 09:18:39 +0200 Subject: [PATCH 07/20] Switch all headings in to h4 - Avoid them showing up in the TOC on the right hand side as those links don't work for inactive tab, and appear sequentially which is a bit confusing - Slightly "Discourage" user deep linking to them, as that often won't work with the inactive tabs. - More emphasis you're finished with the tabbed section as we're back to another bigger heading --- .../getting-started/install-enterprise.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index f9c4627026..f20a8effe9 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -163,7 +163,7 @@ kubectl create secret generic oidc-auth \ Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identities will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly, but we recommend reading the [service account](#gitops-dashboard-service-account-permissions) and [user permissions](#user-permissions) pages to understand which actions are needed for Weave GitOps to function correctly. -### Customization +#### 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). @@ -211,7 +211,7 @@ There are two separate configuration keys. You can override them separately. The -### Configuring OIDC with Dex and GitHub +#### Configuring OIDC with Dex and GitHub This example uses [Dex](https://dexidp.io/) and its [GitHub connector](https://dexidp.io/docs/connectors/github/) to show you how to log in to the Weave GitOps dashboard by authenticating with your GitHub account. It assumes you have already installed Weave GitOps on a Kubernetes cluster, per the instructions above, and have also [enabled TLS](#tls-configuration). Dex is an identity service that uses [OpenID Connect](https://openid.net/connect/) to @@ -238,7 +238,7 @@ kubectl create secret generic github-client \ --from-literal=client-secret=${GITHUB_CLIENT_SECRET} ``` -### Deploy Dex +#### Deploy Dex Use `HelmRepository` and `HelmRelease` objects to let Flux deploy everything. @@ -424,7 +424,7 @@ roleRef: -### Set up a Static User +#### Set up a Static User For a static user, add `staticPasswords` to the `config`: @@ -447,7 +447,7 @@ echo -n $PASSWORD | gitops get bcrypt-hash $2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q ``` -### OIDC Login +#### OIDC Login Using the "Login with OIDC Provider" button: @@ -477,7 +477,7 @@ and development environments, or if you need to activate emergency access to a d Note also that this mechanism only exists for a single user. You will not be able to create multiple users. Weave GitOps does not provide its own authentication mechanism. For secure and fully-featured authentication we **strongly recommend** using an OIDC provider, as described in the other tab. ::: -### Configuring the Emergency User +#### Configuring the Emergency User Before you log in via the emergency 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. @@ -500,14 +500,14 @@ kubectl create secret generic cluster-user-auth \ You should now be able to login via the cluster user account using your chosen username and password. -### Updating the Emergency User +#### Updating the Emergency User To change either the username or the password, recreate the `cluster-user-auth` with the new details. Only one emergency user can be created this way. To add more users, enable an OIDC provider. -### User Permissions +#### User Permissions By default, both a ClusterRole and Role are generated for the emergency user. Both have the same permissions, with the former being optional and the latter being From 17b9d421235fef98d6aee044c49450980f6899e4 Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Thu, 10 Aug 2023 09:40:14 +0200 Subject: [PATCH 08/20] Fixes links to emergency user --- .../docs/enterprise/getting-started/install-enterprise.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index f20a8effe9..4e9a16f141 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -619,7 +619,7 @@ The primary way Weave GitOps queries the Kube API is via `impersonation`. The pe 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](../emergency-user) credentials or OIDC. Then it makes Kube API calls on the user's +cluster user](../../configuration/emergency-user.mdx) credentials or OIDC. Then it makes Kube API calls on the user's behalf. This is equivalent to making a kubectl call like: ```bash @@ -648,7 +648,7 @@ rbac: - qa-team ``` In this example, the application can only impersonate the group's admin, dev-team, -and qa-team. This also implicitly disables the [emergency cluster user](../emergency-user)). +and qa-team. This also implicitly disables the [emergency cluster user](../../configuration/emergency-user.mdx)). Unfortunately, not all OIDC providers support groups. You may need to manually enumerate users—for example: From 512f228dfc6de4ebddc841418c2721920c78c98d Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Thu, 10 Aug 2023 09:50:54 +0200 Subject: [PATCH 09/20] Revert "Fix up image refs" This reverts commit 2aea43d61617dede542495a0b83910d857a791a8. --- .../enterprise/getting-started/install-enterprise.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 4e9a16f141..cbf754b11f 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -229,7 +229,7 @@ metadata: Get a GitHub ClientID and Client secret by creating a [new OAuth application](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). -![GitHub OAuth configuration](/img/guides/setting-up-dex/github-oauth-application.png) +![GitHub OAuth configuration](/img/enterprise/getting-started/install-enterprise/github-oauth-application.png) ```bash kubectl create secret generic github-client \ @@ -451,20 +451,20 @@ $2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q Using the "Login with OIDC Provider" button: -![Login page](/img/guides/setting-up-dex/oidc-login.png) +![Login page](/img/enterprise/getting-started/install-enterprise/oidc-login.png) We have to authorize the GitHub OAuth application: -![GitHub OAuth page](/img/guides/setting-up-dex/github-auth.png) +![GitHub OAuth page](/img/enterprise/getting-started/install-enterprise/github-auth.png) After that, grant access to Dex: -![Dex grant access](/img/guides/setting-up-dex/dex-auth.png) +![Dex grant access](/img/enterprise/getting-started/install-enterprise/dex-auth.png) Now we are logged in with our GitHub user and can see all of the resources we have access to: -![UI logged in](/img/guides/setting-up-dex/ui-logged-in.png) +![UI logged in](/img/enterprise/getting-started/install-enterprise/ui-logged-in.png) From a785c853000b3b22b8ffa0e6fbe4b67935625a47 Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Thu, 10 Aug 2023 09:51:05 +0200 Subject: [PATCH 10/20] Revert "Fixes links to emergency user" This reverts commit 17b9d421235fef98d6aee044c49450980f6899e4. --- .../docs/enterprise/getting-started/install-enterprise.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index cbf754b11f..c178671509 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -619,7 +619,7 @@ The primary way Weave GitOps queries the Kube API is via `impersonation`. The pe 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](../../configuration/emergency-user.mdx) credentials or OIDC. Then it makes Kube API calls on the user's +cluster user](../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 @@ -648,7 +648,7 @@ rbac: - qa-team ``` In this example, the application can only impersonate the group's admin, dev-team, -and qa-team. This also implicitly disables the [emergency cluster user](../../configuration/emergency-user.mdx)). +and qa-team. This also implicitly disables the [emergency cluster user](../emergency-user)). Unfortunately, not all OIDC providers support groups. You may need to manually enumerate users—for example: From 9a9092b96b00ede5e4d42235ee27a5a8801d60a7 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Thu, 10 Aug 2023 10:00:21 +0200 Subject: [PATCH 11/20] Update install-enterprise.mdx --- website/docs/enterprise/getting-started/install-enterprise.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index c178671509..7087967120 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -35,7 +35,6 @@ There is no need to install the open source version of Weave GitOps before insta To get up and running with Weave GitOps Enterprise: - create a Kubernetes cluster -- install Weave GitOps Enterprise, using the `gitops-ee bootstrap` command - add your cluster to kubeconfig—which you'll get from Kubernetes—so that the kubeconfig correctly points to the management cluster - create a Git repository; in the instructions below, we refer to a `fleet-infra` repository - configure your Git client properly (if using GitHub, for example, From 590447c69e2db160c047155152e0b43a61d48af4 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Thu, 10 Aug 2023 10:40:00 +0200 Subject: [PATCH 12/20] Update install-enterprise.mdx Moves entitlements step to later in the prereqs section --- .../getting-started/install-enterprise.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 7087967120..9b9c447636 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -43,12 +43,6 @@ then review their docs on [setting your username](https://docs.github.com/en/get - obtain a valid entitlement secret from Weaveworks and apply it to your cluster - install a compatible version of Flux onto your cluster; see below for how-to guidance -As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster: - -```bash -kubectl apply -f entitlements.yaml -``` - ### Install the Weave GitOps Enterprise CLI Tool To do this, you can use either brew or curl. @@ -108,6 +102,14 @@ flux bootstrap gitlab \ +### Apply Your Entitlements Secret to Your Cluster + +As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster: + +```bash +kubectl apply -f entitlements.yaml +``` + Your private GitHub repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo. * **owner**: The username (or organization) of the Git repository From bd5a399de39df73861b7122b1a8f7ced375ff4d1 Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Mon, 14 Aug 2023 09:31:52 +0200 Subject: [PATCH 13/20] Update TLS section --- .../getting-started/install-enterprise.mdx | 48 +++++++------------ 1 file changed, 17 insertions(+), 31 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 9b9c447636..1c0497a05b 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -102,15 +102,7 @@ flux bootstrap gitlab \ -### Apply Your Entitlements Secret to Your Cluster - -As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster: - -```bash -kubectl apply -f entitlements.yaml -``` - -Your private GitHub repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo. +Your private Git repo should have a clusters/management folder that includes the manifests Flux needs to operate, and that also generates a key value pair for Flux to access the repo. * **owner**: The username (or organization) of the Git repository * **repository**: Git repository name @@ -121,6 +113,14 @@ Your private GitHub repo should have a clusters/management folder that includes At this point your Flux management cluster should be running. Take a look at the repository you created earlier. +### Apply Your Entitlements Secret to Your Cluster + +As noted above, you receive your entitlements secret by contacting sales@weave.works. Use this command to apply it to the cluster: + +```bash +kubectl apply -f entitlements.yaml +``` + ## Set up Authentication and RBAC ### Securing Access to the Dashboard @@ -1066,36 +1066,22 @@ WGE is now configured to ask users for authorization the next time a pull reques ## TLS Configuration -By default, the dashboard will listen on 0.0.0.0:9001 with TLS disabled and -without exposing any external connection. - -We don't recommend exposing services without TLS. Without a certificate, you -can't be sure if you're using the correct service, and the traffic will be easily -monitored—or even tampered with. All communication between the user and an endpoint -with TLS will be encrypted. +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. -To expose an external connection, you must first configure TLS. TLS termination -can be provided via an ingress controller or directly by the dashboard. In -either case, the Helm Release must be updated. To have the dashboard itself -handle TLS, you must create a `tls` secret containing the cert and key: +It can then be accessed via port-forwarding: -```cli -kubectl create secret tls my-tls-secret \ - --cert=path/to/cert/file \ - --key=path/to/key/file -``` +`kubectl port-forward --namespace flux-system svc/clusters-service 8000:8000` -and reference it from the Helm release: +If you're using an ingress controller to terminate TLS you can disable it in the Helm release: ```yaml values: - serverTLS: - enabled: true - secretName: "my-tls-secret" + tls: + enabled: false ``` -If you prefer to delegate TLS handling to the ingress controller instead, your -helm release should look like: +Other ingress conguration changes can be made via the ingress configuration ```yaml values: From e062a0d6848fee52a150a6bdbb6b2cffbef18f23 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Mon, 14 Aug 2023 09:47:10 +0200 Subject: [PATCH 14/20] Update install-enterprise.mdx Removes unavailable Helm values --- .../enterprise/getting-started/install-enterprise.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 1c0497a05b..518c0d28e0 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -605,15 +605,6 @@ These allow the pod to do three things: to store the emergency cluster user account and OIDC configuration (see [securing access to the dashboard](#securing-access-to-the-dashboard)) -### The Helm Values - -| Value | Description | Default | -|-----------------------------------|---------------------------------------------------------------------|--------------------------------------| -| `rbac.impersonationResources` | Which resource types the service account can impersonate | `["users", "groups"]` | -| `rbac.impersonationResourceNames` | Specific users, groups or services account that can be impersonated | `[]` | -| `rbac.viewSecretsResourceNames` | Specific secrets that can be read | `["cluster-user-auth", "oidc-auth"]` | - - ### Impersonation The primary way Weave GitOps queries the Kube API is via `impersonation`. The permissions granted to users and groups that Weave GitOps From 004cd66acd88e7f77ffae33cc615fbcebaa23937 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Mon, 14 Aug 2023 09:48:07 +0200 Subject: [PATCH 15/20] Update website/docs/enterprise/getting-started/install-enterprise.mdx Co-authored-by: Simon --- website/docs/enterprise/getting-started/install-enterprise.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 518c0d28e0..605f515b57 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -576,7 +576,7 @@ the cluster. ### GitOps Dashboard Service Account Permissions This section covers the service account [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -for the Weave GitOps application, which the WGE UI requires to work. The default permissions are defined in the [Helm chart](https://github.com/weaveworks/weave-gitops/tree/main/charts/gitops-server/templates/role.yaml), which will generate a cluster role with the following permissions: +for the Weave GitOps application, which the WGE UI requires to work. The default permissions will generate a cluster role with the following permissions: ```yaml rules: From 00577d0d36440c79882af7b2357d1c592e465915 Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Mon, 14 Aug 2023 09:49:12 +0200 Subject: [PATCH 16/20] Update install-enterprise.mdx Removes impersonation section --- .../getting-started/install-enterprise.mdx | 31 ------------------- 1 file changed, 31 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 605f515b57..7e3ef15cef 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -625,37 +625,6 @@ permissions is very important. Without proper restrictions the application can i very powerful `users` or `groups`. For example, the `system:masters` is a group generally bound to the `cluster-admin` role, which can do anything. -### Configuring Impersonation - -We highly recommend limiting which users and groups the -application can impersonate by setting `rbac.impersonationResourceNames` in -the Helm chart's `values`. e.g.: - -```yaml -rbac: - impersonationResources: ["groups"] - impersonationResourceNames: - - admin - - dev-team - - qa-team -``` -In this example, the application can only impersonate the group's admin, dev-team, -and qa-team. This also implicitly disables the [emergency cluster user](../emergency-user)). - -Unfortunately, not all OIDC providers support groups. You may need to -manually enumerate users—for example: - -```yaml -rbac: - impersonationResources: ["users"] - impersonationResourceNames: - - aisha@example.com - - bill@example.com - - wego-admin # enable the emergency cluster user -``` - -A better, albeit more involved, solution is to set up an OIDC connector like Dex and use that to manage groups for you. - ### Get Namespaces The application itself uses get namespace permissions to pre-cache the list of From 4bb90aed2249d03eb56277474678d8fc1f1ef01a Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Mon, 14 Aug 2023 09:50:57 +0200 Subject: [PATCH 17/20] Update install-enterprise.mdx Removes unavailable restriction --- .../enterprise/getting-started/install-enterprise.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 7e3ef15cef..d3085e276c 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -776,15 +776,6 @@ You can then create three groups: no `patch` permissions. - Aisha, Brian, June and Jo are all members -The Weave GitOps service account can then be configured with: -```yaml -rbac: - impersonationResourceNames: ["wego-admin", "wego-team-a-admin", "wego-readonly"] - impersonationResources: ["groups"] -``` - -so that only these three groups can be `impersonated` by the service account. - :::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 From 64b01f311e60bdb7d1fc27ddfae92552ec65069f Mon Sep 17 00:00:00 2001 From: Lauri Apple Date: Mon, 14 Aug 2023 10:02:48 +0200 Subject: [PATCH 18/20] Update install-enterprise.mdx Update code --- .../getting-started/install-enterprise.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index d3085e276c..668ddf6491 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -382,23 +382,23 @@ metadata: namespace: flux-system 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"] + resources: ["users", "groups" ] + verbs: [ "impersonate" ] - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] + resources: [ "secrets" ] + verbs: [ "get", "list", "watch" ] + - apiGroups: ["cluster.x-k8s.io"] + resources: [ "clusters" ] + verbs: [ "get", "list", "watch" ] + - apiGroups: ["gitops.weave.works"] + resources: [ "gitopsclusters" ] + verbs: [ "create", "delete", "get", "list", "patch", "update", "watch" ] + - apiGroups: ["gitops.weave.works"] + resources: ["gitopsclusters/finalizers"] + verbs: ["update"] + - apiGroups: ["gitops.weave.works"] + resources: ["gitopsclusters/status"] + verbs: ["get", "patch", "update"] ``` From 6a5d81f0e559768fd5d9d478f3e366ba17dba5fa Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Tue, 15 Aug 2023 08:36:25 +0200 Subject: [PATCH 19/20] Revert "Update install-enterprise.mdx" This reverts commit 64b01f311e60bdb7d1fc27ddfae92552ec65069f. --- .../getting-started/install-enterprise.mdx | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 668ddf6491..d3085e276c 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -382,23 +382,23 @@ metadata: namespace: flux-system rules: - apiGroups: [""] - resources: ["users", "groups" ] - verbs: [ "impersonate" ] + 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: [ "secrets" ] - verbs: [ "get", "list", "watch" ] - - apiGroups: ["cluster.x-k8s.io"] - resources: [ "clusters" ] - verbs: [ "get", "list", "watch" ] - - apiGroups: ["gitops.weave.works"] - resources: [ "gitopsclusters" ] - verbs: [ "create", "delete", "get", "list", "patch", "update", "watch" ] - - apiGroups: ["gitops.weave.works"] - resources: ["gitopsclusters/finalizers"] - verbs: ["update"] - - apiGroups: ["gitops.weave.works"] - resources: ["gitopsclusters/status"] - verbs: ["get", "patch", "update"] + resources: ["events"] + verbs: ["get", "watch", "list"] ``` From 285d32d8d60d4adc6e0cae2ce0d35a4577688697 Mon Sep 17 00:00:00 2001 From: Simon Howe Date: Tue, 15 Aug 2023 08:59:46 +0200 Subject: [PATCH 20/20] Remove comments in yaml about configuring via values.rbac - WGE doesn't support that --- .../getting-started/install-enterprise.mdx | 25 ++++++------------- 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index d3085e276c..7d8747f3cc 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -576,23 +576,16 @@ the cluster. ### GitOps Dashboard Service Account Permissions This section covers the service account [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -for the Weave GitOps application, which the WGE UI requires to work. The default permissions will generate a cluster role with the following 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: -# Used to query the cluster - apiGroups: [""] - resources: ["users", "groups"] # set by rbac.impersonationResources + resources: ["users", "groups"] verbs: [ "impersonate" ] - # resourceNames: [] # set by rbac.impersonationResourceNames -# Used to get OIDC/static user credentials for login - apiGroups: [""] resources: [ "secrets" ] verbs: [ "get", "list" ] - resourceNames: # set by rbac.viewSecretsResourceNames - - "cluster-user-auth" - - "oidc-auth" -# The service account needs to read namespaces to know where it can query - apiGroups: [ "" ] resources: [ "namespaces" ] verbs: [ "get", "list" ] @@ -605,7 +598,7 @@ These allow the pod to do three things: to store the emergency cluster user account and OIDC configuration (see [securing access to the dashboard](#securing-access-to-the-dashboard)) -### Impersonation +#### 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. @@ -625,13 +618,13 @@ permissions is very important. Without proper restrictions the application can i 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 +#### 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 +#### 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 @@ -640,12 +633,6 @@ for the [emergency user](../emergency-user), and the latter holds OIDC configura The application needs to be able to access these secrets in order to authenticate users. -#### Configuring Secrets - -The `rbac.viewSecretsResourceNames` value allows the operator to change which secrets the -application can read. This is mostly so that the secret can be removed if the emergency user is not -configured, or if the secret _is_ in use but renamed. - ### User Permissions This section discusses the [Kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) @@ -683,6 +670,8 @@ rules: 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.