diff --git a/website/docs/cluster-management/cluster-management-intro.mdx b/website/docs/cluster-management/cluster-management-intro.mdx index 9a3b60ac14..e3a590fbc9 100644 --- a/website/docs/cluster-management/cluster-management-intro.mdx +++ b/website/docs/cluster-management/cluster-management-intro.mdx @@ -42,9 +42,9 @@ Finally, you can create a pull request to your target cluster and see it on your ## Follow Our User Guide -Our user guide pages provides two pathways to deployment: +Our user guide provides two pathways to deployment: - One path that shows you how to manage clusters [without adding Cluster API](managing-clusters-without-capi.mdx). Join a cluster by hooking WGE to it, then install an application on that cluster. -- An **optional** path that shows you how to create, provision, and delete your first API cluster with [EKS/CAPA](../cluster-management/deploying-capa-eks.mdx). +- An **optional** path that shows you how to create, provision, and delete your first API cluster with [EKS/CAPA](../enterprise/getting-started/deploying-capa-eks.mdx). Just click the option you want to get started with, and let's go. diff --git a/website/docs/cluster-management/managing-clusters-without-capi.mdx b/website/docs/cluster-management/managing-clusters-without-capi.mdx index 2b872fbf46..4a04953013 100644 --- a/website/docs/cluster-management/managing-clusters-without-capi.mdx +++ b/website/docs/cluster-management/managing-clusters-without-capi.mdx @@ -12,7 +12,7 @@ import BrowserOnly from "@docusaurus/BrowserOnly"; # Managing Clusters Without Cluster API -You do **not** need Cluster API to add your Kubernetes cluster to Weave Gitops Enterprise. The only thing you need is a secret containing a valid `kubeconfig`. +You do **not** need Cluster API to add your Kubernetes cluster to Weave GitOps Enterprise. The only thing you need is a secret containing a valid `kubeconfig`. import TOCInline from "@theme/TOCInline"; ; @@ -58,7 +58,7 @@ Here's how to create a kubeconfig secret. name: impersonate-user-groups subjects: - kind: ServiceAccount - name: demo-01 + name: wgesa namespace: default roleRef: kind: ClusterRole @@ -154,7 +154,13 @@ Here's how to create a kubeconfig secret. -5. Obtain the cluster certificate (CA). How you do this depends on your cluster. If you're using GKE, for example, you can view the CA on the GCP Console: Cluster->Details->Endpoint->”Show cluster certificate”. You'll need to copy the contents of the certificate into the `ca.crt` file used below. +5. Obtain the cluster certificate (CA). How you do this depends on your cluster. + +- **AKS**: Visit the [Azure user docs](https://learn.microsoft.com/en-us/azure/aks/certificate-rotation) for more information. +- **EKS**: Visit the [EKS docs](https://docs.aws.amazon.com/eks/latest/userguide/cert-signing.html) for more information. +- **GKE**: You can view the CA on the GCP Console: Cluster->Details->Endpoint->”Show cluster certificate”. + +You'll need to copy the contents of the certificate into the `ca.crt` file used below. ```bash CLUSTER_NAME=demo-01 \ @@ -170,7 +176,7 @@ Here's how to create a kubeconfig secret. - CA_CERTIFICATE: include the path to the CA certificate file of the cluster - TOKEN: add the token of the service account retrieved in the previous step -7. Finally, create a secret for the generated kubeconfig: +7. Finally, create a secret for the generated kubeconfig in the WGE management cluster: ```bash kubectl create secret generic demo-01-kubeconfig \ @@ -224,9 +230,7 @@ Then update the `GITHUB_USER` variable to point to your repository To connect your cluster, you need to add some common RBAC rules into the `clusters/bases` folder. When a cluster is provisioned, by default it will reconcile all the manifests in `./clusters//` and `./clusters/bases`. -To display Applications and Sources in the UI we need to give the logged in user permissions to inspect the new cluster. - -Adding common RBAC rules to `./clusters/bases/rbac` is an easy way to configure this! +To display Applications and Sources in the UI, we need to give the logged-in user permissions to inspect the new cluster. Adding common RBAC rules to `./clusters/bases/rbac` is an easy way to configure this. import WegoAdmin from "!!raw-loader!./assets/rbac/wego-admin.yaml"; diff --git a/website/docs/configuration/emergency-user.mdx b/website/docs/configuration/emergency-user.mdx deleted file mode 100644 index c5b1548aa2..0000000000 --- a/website/docs/configuration/emergency-user.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Emergency Cluster User Account ---- - -:::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 [here](../oidc-access). -::: - -## Configuring the emergency user - -Before you login 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. - -Note that only one emergency user can be created this way. To add more users, -enable an [OIDC provider](../oidc-access). - -## User permissions - -By default both a ClusterRole and Role are generated for the emergency user. -Both have the same permissions with 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 which were created on -the cluster. -::: diff --git a/website/docs/configuration/oidc-access.mdx b/website/docs/configuration/oidc-access.mdx deleted file mode 100644 index c877770616..0000000000 --- a/website/docs/configuration/oidc-access.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: OIDC Provider ---- - -# Login via an OIDC provider - -You may decide to give your engineering teams access to the dashboard, in order to view and manage their workloads. In this case, you will want to secure access to the dashboard and restrict who can interact with it. Weave GitOps integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the permissions for the dashboard users. - -## Background - -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, this information is used by Weave GitOps 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 also the dashboard. - -## Configuration - -In order to login via your OIDC provider, you need to 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 that has been setup for Weave GitOps in the issuer | | -| `clientSecret` | The client secret that has been setup for Weave GitOps in the issuer | | -| `redirectURL` | The redirect URL that has been setup 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 setup with a client ID/secret and the redirect URL of the dashboard. - -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' identity 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 it is recommended to read the [service account](service-account-permissions.mdx) and [user](user-permissions.mdx) permissions pages to understand which actions are needed for Weave GitOps to function correctly. - -## Customizing - -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, and the "email", and "groups" scopes are commonly used as unique identifiers in organisations. - -We use "offline_access" to allow 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" and "scopes" would be requested, in addition to "openid". - -### 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 we communicate 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= \ - --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, these should match your `kube-apiserver` configuration. - -### 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: - -#### Weave Gitops - -```yaml -envVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` - -#### Weave Gitops Enterprise - -```yaml -extraEnvVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` \ No newline at end of file diff --git a/website/docs/configuration/recommended-rbac-configuration.mdx b/website/docs/configuration/recommended-rbac-configuration.mdx deleted file mode 100644 index 03721cfdf3..0000000000 --- a/website/docs/configuration/recommended-rbac-configuration.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Recommended RBAC Configuration ---- - -This page summarises the contents of the [securing access to the dashboard](securing-access-to-the-dashboard.mdx), -[service account permissions](service-account-permissions.mdx) and [user permissions](user-permissions.mdx). They should be -read in addition to this page in order to understand the suggestions made here and -their ramifications. - -This page is purposefully vague as the intention is to give a broad idea of how -such a system could be implemented, not the specifics as that will be dependent -on your specific circumstances and goals. - -## Summary - -The general recommendation is to use OIDC and a small number of groups that -Weave GitOps can impersonate. - -OIDC is the recommended method for managing authentication as it 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](../guides/setting-up-dex.md)). - -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 set up - -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 readonly otherwise -* June and Jo, developers in team-A who should have read-only access to Weave GitOps - -You could then create 3 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'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 & 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 un-intended consequences (e.g. 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 readonly role to the readonly 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 ---- -``` - -
diff --git a/website/docs/configuration/securing-access-to-the-dashboard.mdx b/website/docs/configuration/securing-access-to-the-dashboard.mdx deleted file mode 100644 index b0f40ae381..0000000000 --- a/website/docs/configuration/securing-access-to-the-dashboard.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Securing access to the dashboard ---- - -## Dashboard Login - -There are 2 supported methods for logging in to the dashboard: -- [Login via an OIDC provider](../oidc-access) -- [Login via a cluster user account](../emergency-user) (not recommended) - -The recommended method is to integrate with an OIDC provider, -as this will let you control permissions for existing users and groups that have -already been configured to use OIDC. However, it is also possible to use the Emergency Cluster -User Account to login, if an OIDC provider is not available to use. -Both methods work with standard Kubernetes RBAC. diff --git a/website/docs/configuration/service-account-permissions.mdx b/website/docs/configuration/service-account-permissions.mdx deleted file mode 100644 index ef81eb1253..0000000000 --- a/website/docs/configuration/service-account-permissions.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Dashboard Runtime Permissions ---- - -# GitOps Dashboard Service Account Permissions - -:::danger Important -This doc covers the service account [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -for the **Weave Gitops application** itself (ie. the permissions the Dashboard needs to work). -For the service account for the **cluster user** role (ie. for the user accessing the -GitOps Dashboard), see the page [here](user-permissions.mdx). -::: - -The default permissions of the service account 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 the users' permissions) -* Read the `cluster-user-auth` and `oidc-auth` secrets, which are the default secrets - to store the emergency cluster user account and OIDC configuration (see - [securing access to the dashboard](securing-access-to-the-dashboard.mdx)) - -## 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 -application (not the cluster) authenticates the user (either via the [emergency -cluster user](../emergency-user) credentials or OIDC) then makes calls to the Kube API 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 been granted permissions to get -deployments within the cluster then this will return them. The same occurs -within the application. This makes the proper configuration of the application's -permissions very important as, without proper restrictions it can impersonate -very powerful `users` or `groups`. For example, the `system:masters` is group -is generally bound to the `cluster-admin` role which can do anything. - -For more details of the permissions needed by the user or group see the -[user permissions](user-permissions.mdx) guide. - -### Configuring impersonation - -It is highly recommended that you limit which users and groups that 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 groups admin, dev-team -and qa-team (this also, implicitly disables the [emergency cluster user](../emergency-user)). - -Unfortunately not all OIDC providers support groups so 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](../guides/setting-up-dex.md) 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, if the emergency user is not -configured, that secret can be removed, or if the secret _is_ in use but renamed. diff --git a/website/docs/configuration/tls.md b/website/docs/configuration/tls.md deleted file mode 100644 index b9932d6ff6..0000000000 --- a/website/docs/configuration/tls.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TLS and Certificates ---- - -## TLS configuration - -By default the dashboard will listen on 0.0.0.0:9001 with TLS disabled and -without exposing any external connection. - -Exposing services without TLS if not recommended. Without a certificate, a user -can't be sure they are using the right 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 ... -``` - -## cert-manager - -Install [cert-manager](../guides/cert-manager.md) and request a `Certificate` in -the `flux-system` namespace. Provide the name of secret associated with the -certificate to the weave-gitops-enterprise HelmRelease as described above. diff --git a/website/docs/configuration/user-permissions.mdx b/website/docs/configuration/user-permissions.mdx deleted file mode 100644 index 2ec436f633..0000000000 --- a/website/docs/configuration/user-permissions.mdx +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: User Permissions ---- -import TierLabel from "../_components/TierLabel"; - -This is an explanation of the [kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -needed by users/groups of the Weave GitOps application. As covered in -[service account permissions](service-account-permissions.mdx) -the primary way that the application interacts with the Kube API is via [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). -This means that the permissions granted to the users and groups that Weave GitOps -can impersonate determine the scope of actions that it can take within your cluster. - -At a minimum, a User should be bound to Role in the `flux-system` namespace (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 resources that Flux works with directly, including the one from TF-controller. - -| Api Group | Resources | Permissions | -| ------------------------------ | ----------------------------------------------------------------------- | ---------------- | -| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch | -| helm.toolkit.fluxcd.io | helmreleases | get, list, patch | -| source.toolkit.fluxcd.io | buckets, helmcharts, gitrepositories, helmrepositories, ocirepositories | get, list, patch | -| notification.toolkit.fluxcd.io | providers, alerts | get, list | -| infra.contrib.fluxcd.io | terraforms | get, list, patch | - -In order for Weave GitOps to be able to accurately display the state of Flux it -needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses. This is done using the -`get` and `list` permissions - -The `patch` permissions are used for 2 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 the annotations -of the resource. These features work the same way `flux suspend`, -`flux resume` and `flux reconcile` does on the CLI. - -### Resources managed via Flux - -| Api Group | Resources | Permissions | -|---------------------------|--------------------------------------------------------------------------------|------------------| -| "" | configmaps, secrets, pods, services, persistentvolumes, persistentvolumeclaims | get, list, watch | -| apps | deployments, replicasets, statefulsets | get, list, watch | -| batch | jobs, cronjobs | get, list, watch | -| autoscaling | horizontalpodautoscalers | get, list, watch | -| rbac.authorization.k8s.io | roles, clusterroles, rolebindings, clusterrolebindings | 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 - -The primary method by which Flux communicates the status of itself is by events, -these will show when reconciliations start and stop, whether they're successful -and information as to why they're not. - -## Weave GitOps Enterprise - -Weave GitOps Enterprise extends Weave GitOps OSS by adding more roles. These roles may need to be extended further in order to support certain use cases. Some of the most common use cases are described below. - -### Progressive delivery with Flagger - -Weave GitOps Enterprise integrates with Flagger in order to provide a view on progressive delivery deployments. This includes the ability to view all the resources that Flagger manages during its operation. The default ClusterRole `gitops-canaries-reader` includes the minimum permissions necessary for a user to be able to view canary object details, metric template object details and canary related events. - -When Flagger is configured to integrate with a service mesh such as Linkerd or Istio for the rollout, then this ClusterRole needs to be extended so that it can read the additional service mesh resources being generated by Flagger. Note that currently, in order to display service mesh or ingress related resources, we require `spec.provider` to be set in each canary resource. - -The following table provides a list of all the custom resources that Flagger generates grouped by provider: - -| Provider | API Group | Resource | -| --- | --- | --- | -| AppMesh | appmesh.k8s.aws | virtualnode | -| | appmesh.k8s.aws | virtualrouter | -| | appmesh.k8s.aws | virtualservice | -| Linkerd | split.smi-spec.io | trafficsplit | -| Istio | networking.istio.io | destinationrule | -| | networking.istio.io | virtualservice | -| Contour | projectcontour.io | httpproxy | -| Gloo | gateway.solo.io | routetable | -| | gloo.solo.io | upstream | -| Nginx | networking.k8s.io | ingress | -| Skipper | networking.k8s.io | ingress | -| Traefik | traefik.containo.us | traefikservice | -| Open Service Mesh | split.smi-spec.io | trafficsplit | -| Kuma | kuma.io | trafficroute | -| GatewayAPI | gateway.networking.k8s.io | httproute | - -For example, the following manifest shows how `gitops-canaries-reader` has been extended to allow the user for viewing TrafficSplit resources when Linkerd is used: - -
Expand to see example canary reader RBAC - -```yaml title="gitops-canaries-reader.yaml" -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitops-canaries-reader -rules: -- apiGroups: - - flagger.app - resources: - - canaries - - metrictemplates - verbs: - - get - - list -- apiGroups: - - "" - resources: - - events - verbs: - - get - - watch - - list -# Additional permissions for Linkerd resources are added below -- apiGroups: - - split.smi-spec.io - resources: - - trafficsplits - verbs: - - get - - list -``` - -
- -#### Setting up remote cluster permissions - -In order to view canaries in a remote cluster from the management cluster, you need to consider the following: -- The service account used to access the remote cluster needs to be able to list namespaces and custom resource definitions in the given cluster. It additionally needs to be able to impersonate users and groups. -- The user or group that logs in to the management cluster, needs appropriate permissions to certain resources of the remote cluster. - -For example, applying the following manifest on remote clusters, ensures that the `wego-admin` user will be able to view canary information from within the Weave GitOps Enterprise UI on the management cluster: - -
Expand to see example of remote cluster canary reader - -```yaml title="remote-cluster-service-user-rbac.yaml" -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: user-groups-impersonator -rules: - - apiGroups: [""] - resources: ["users", "groups"] - verbs: ["impersonate"] - - apiGroups: [""] - resources: ["namespaces"] - verbs: ["get", "list"] - - apiGroups: ["apiextensions.k8s.io"] - resources: ["customresourcedefinitions"] - verbs: ["get", "list"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: impersonate-user-groups -subjects: - - kind: ServiceAccount - name: remote-cluster-01 # Service account created in remote cluster - namespace: default -roleRef: - kind: ClusterRole - name: user-groups-impersonator - apiGroup: rbac.authorization.k8s.io ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: canary-reader -rules: - - apiGroups: [""] - resources: [ "events", "services" ] - verbs: [ "get", "list", "watch" ] - - apiGroups: [ "apps" ] - resources: [ "*" ] - verbs: [ "get", "list" ] - - apiGroups: [ "autoscaling" ] - resources: [ "*" ] - verbs: [ "get", "list" ] - - apiGroups: [ "flagger.app" ] - resources: [ "canaries", "metrictemplates"] - verbs: [ "get", "list", "watch" ] - - apiGroups: [ "helm.toolkit.fluxcd.io" ] - resources: [ "helmreleases" ] - verbs: [ "get", "list" ] - - apiGroups: [ "kustomize.toolkit.fluxcd.io" ] - resources: [ "kustomizations" ] - verbs: [ "get", "list" ] - - apiGroups: [ "source.toolkit.fluxcd.io" ] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list" ] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: read-canaries -subjects: -- kind: User - name: wego-admin # User logged in management cluster, impersonated via service account - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: canary-reader - apiGroup: rbac.authorization.k8s.io -``` - -
- -You may need to add more users/groups to the `read-canaries` ClusterRoleBinding to ensure additional users can view canary information from within the Weave GitOps Enterprise UI. diff --git a/website/docs/cluster-management/deploying-capa-eks.mdx b/website/docs/enterprise/getting-started/deploying-capa-eks.mdx similarity index 98% rename from website/docs/cluster-management/deploying-capa-eks.mdx rename to website/docs/enterprise/getting-started/deploying-capa-eks.mdx index 83015e1a25..8b8ab3f273 100644 --- a/website/docs/cluster-management/deploying-capa-eks.mdx +++ b/website/docs/enterprise/getting-started/deploying-capa-eks.mdx @@ -28,7 +28,7 @@ You'll need to install the following software before continuing with these instr - the AWS Command Line Interface/`aws cli` [(source)](https://aws.amazon.com/cli/) - `clusterctl` >= v1.1.3 [(source)](https://github.com/kubernetes-sigs/cluster-api/releases); follow [these steps](https://cluster-api-aws.sigs.k8s.io/getting-started.html#install-clusterctl) to initialise the cluster and enable feature gates - `clusterawsadm` >= v1.1.0, following [Cluster API's instructions](https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases) -- Make sure you have a management cluster. If you followed the Weave GitOps Enterprise [installation guide](../enterprise/getting-started/install-enterprise.mdx), you'll have done this already. +- Make sure you have a management cluster. If you followed the Weave GitOps Enterprise [installation guide](./install-enterprise.mdx), you'll have done this already. - Configure your `AWS_ACCESS_KEY_ID`and `AWS_SECRET_ACCESS_KEY` with either `aws configure` or by exporting it in the current shell. - Set the `GITHUB_TOKEN` as an environment variable in the current shell. It should have permissions to create Pull Requests against the cluster config repo. diff --git a/website/docs/explorer/configuration.mdx b/website/docs/explorer/configuration.mdx index 862982c81f..a2249323c9 100644 --- a/website/docs/explorer/configuration.mdx +++ b/website/docs/explorer/configuration.mdx @@ -95,7 +95,7 @@ Query results are filtered honouring the access determined via RBAC. [GitopsClusters](../cluster-management/managing-clusters-without-capi.mdx/#connect-a-cluster) define the connection and security context that Explorer leverages to collect data from leaf clusters. Given that you have followed the indications -in [setup RBAC](../configuration/service-account-permissions.mdx), the GitopsCluster service account is able to impersonate any user or group. +in [setup RBAC](../enterprise/getting-started/install-enterprise.mdx#gitops-dashboard-service-account-permissions), the GitopsCluster service account is able to impersonate any user or group. :::tip diff --git a/website/docs/guides/setting-up-dex.md b/website/docs/guides/setting-up-dex.md deleted file mode 100644 index b2fcaf2258..0000000000 --- a/website/docs/guides/setting-up-dex.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Configuring OIDC with Dex and GitHub ---- - -In this guide we will show you how to enable users to login to the Weave GitOps dashboard by authenticating with their GitHub account. - -This example uses [Dex][tool-dex] and its GitHub connector, and assumes Weave GitOps has already been installed on a Kubernetes clusters. - -### Pre-requisites - -- A Kubernetes cluster such as [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) cluster running a -[Flux-supported version of Kubernetes](https://fluxcd.io/docs/installation/#prerequisites) -- Weave GitOps is [installed](../open-source/getting-started/install-OSS.mdx) and [TLS has been enabled](../configuration/tls.md). - -## What is Dex? - -[Dex][tool-dex] is an identity service that uses [OpenID Connect][oidc] to -drive authentication for other apps. - -Alternative solutions for identity and access management exist such as [Keycloak](https://www.keycloak.org/). - -[tool-dex]: https://dexidp.io/ -[oidc]: https://openid.net/connect/ - -## Create Dex namespace - -Create a namespace where Dex will be installed: - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: dex -``` - -## Add credentials - -There are a [lot of options][dex-connectors] available with Dex, in this guide we will -use the [GitHub connector][dex-github]. - -We can get a GitHub ClientID and Client secret by creating a -[new OAuth application][github-oauth]. - -![GitHub OAuth configuration](/img/guides/setting-up-dex/github-oauth-application.png) - -```bash -kubectl create secret generic github-client \ - --namespace=dex \ - --from-literal=client-id=${GITHUB_CLIENT_ID} \ - --from-literal=client-secret=${GITHUB_CLIENT_SECRET} -``` - -[dex-connectors]: https://dexidp.io/docs/connectors/ -[dex-github]: https://dexidp.io/docs/connectors/github/ -[github-oauth]: https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app - -## Deploy Dex - -As we did before, we can 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 -``` - -
- -:::note SSL certificate without cert manager -If we don't want to use cert manager, we can remove the related annotation and -use our predefined secret in the `tls` section. -::: - -An important part of the configuration is the `orgs` field on the GitHub -connector. - -```yaml -orgs: -- name: weaveworks - teams: - - team-a - - team-b - - QA -``` - -Here we can define groups under a GitHub organisation. In this example the -GitHub organisation is `weaveworks` and all members of the `team-a`, -`team-b`, and `QA` teams can authenticate. Group membership will be 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"] -``` - -
- -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 static user - -For 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" -``` - -A static user password can be generated with the `gitops` CLI: - -```bash -PASSWORD="" -echo -n $PASSWORD | gitops get bcrypt-hash -$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q -``` - -## OIDC login - -Using the "Login with OIDC Provider" button: - -![Login page](/img/guides/setting-up-dex/oidc-login.png) - -We have to authorize the GitHub OAuth application: - -![GitHub OAuth page](/img/guides/setting-up-dex/github-auth.png) - -After that, grant access to Dex: - -![Dex grant access](/img/guides/setting-up-dex/dex-auth.png) - -Now we are logged in with our GitHub user and we can see all resources we have -access to: - -![UI logged in](/img/guides/setting-up-dex/ui-logged-in.png) diff --git a/website/docs/open-source/getting-started/ui-OSS.mdx b/website/docs/open-source/getting-started/ui-OSS.mdx index 05babca9f8..a860c44dc8 100644 --- a/website/docs/open-source/getting-started/ui-OSS.mdx +++ b/website/docs/open-source/getting-started/ui-OSS.mdx @@ -37,8 +37,8 @@ First, expose the service running on the cluster with this command: kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001 ``` -Next, [open the dashboard](http://localhost:9001/) and login using either the [emergency cluster user](../../configuration/emergency-user.mdx) - or OIDC, based on your [configuration](../../configuration/securing-access-to-the-dashboard.mdx). +Next, [open the dashboard](http://localhost:9001/) and login using either the [emergency cluster user](../../enterprise/getting-started/install-enterprise.mdx#configuring-the-emergency-user) + or OIDC, based on your [configuration](../../enterprise/getting-started/install-enterprise.mdx#securing-access-to-the-dashboard). If you followed the example above, the emergency user will be configured with the username set to `admin`. This means that you can use “admin” as your user name, and the password that you set earlier during installation as `$PASSWORD`. ![Weave GitOps login screen](/img/dashboard-login.png) diff --git a/website/docs/terraform/using-terraform-templates.mdx b/website/docs/terraform/using-terraform-templates.mdx index 2a370d9fe2..1637a79125 100644 --- a/website/docs/terraform/using-terraform-templates.mdx +++ b/website/docs/terraform/using-terraform-templates.mdx @@ -14,7 +14,7 @@ This guide will show you how to use a template to create a Terraform resource in ## CLI Guide ### Prerequisites -- Install [Weave GitOps Enterprise](../enterprise/getting-started/install-enterprise.mdx) and [enable TLS](../configuration/tls.md). +- Install [Weave GitOps Enterprise](../enterprise/getting-started/install-enterprise.mdx) and [enable TLS](../enterprise/getting-started/install-enterprise.mdx#tls-configuration). - Install [Terraform Controller](../terraform/get-started-terraform.mdx). ### 1. Add a template to your cluster diff --git a/website/static/img/guides/setting-up-dex/dex-auth.png b/website/static/img/enterprise/getting-started/install-enterprise/dex-auth.png similarity index 100% rename from website/static/img/guides/setting-up-dex/dex-auth.png rename to website/static/img/enterprise/getting-started/install-enterprise/dex-auth.png diff --git a/website/static/img/guides/setting-up-dex/github-auth.png b/website/static/img/enterprise/getting-started/install-enterprise/github-auth.png similarity index 100% rename from website/static/img/guides/setting-up-dex/github-auth.png rename to website/static/img/enterprise/getting-started/install-enterprise/github-auth.png diff --git a/website/static/img/guides/setting-up-dex/github-oauth-application.png b/website/static/img/enterprise/getting-started/install-enterprise/github-oauth-application.png similarity index 100% rename from website/static/img/guides/setting-up-dex/github-oauth-application.png rename to website/static/img/enterprise/getting-started/install-enterprise/github-oauth-application.png diff --git a/website/static/img/guides/setting-up-dex/oidc-login.png b/website/static/img/enterprise/getting-started/install-enterprise/oidc-login.png similarity index 100% rename from website/static/img/guides/setting-up-dex/oidc-login.png rename to website/static/img/enterprise/getting-started/install-enterprise/oidc-login.png diff --git a/website/static/img/guides/setting-up-dex/ui-logged-in.png b/website/static/img/enterprise/getting-started/install-enterprise/ui-logged-in.png similarity index 100% rename from website/static/img/guides/setting-up-dex/ui-logged-in.png rename to website/static/img/enterprise/getting-started/install-enterprise/ui-logged-in.png diff --git a/website/versioned_docs/version-0.29.0/configuration/emergency-user.mdx b/website/versioned_docs/version-0.29.0/configuration/emergency-user.mdx deleted file mode 100644 index c5b1548aa2..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/emergency-user.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Emergency Cluster User Account ---- - -:::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 [here](../oidc-access). -::: - -## Configuring the emergency user - -Before you login 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. - -Note that only one emergency user can be created this way. To add more users, -enable an [OIDC provider](../oidc-access). - -## User permissions - -By default both a ClusterRole and Role are generated for the emergency user. -Both have the same permissions with 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 which were created on -the cluster. -::: diff --git a/website/versioned_docs/version-0.29.0/configuration/oidc-access.mdx b/website/versioned_docs/version-0.29.0/configuration/oidc-access.mdx deleted file mode 100644 index c877770616..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/oidc-access.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: OIDC Provider ---- - -# Login via an OIDC provider - -You may decide to give your engineering teams access to the dashboard, in order to view and manage their workloads. In this case, you will want to secure access to the dashboard and restrict who can interact with it. Weave GitOps integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the permissions for the dashboard users. - -## Background - -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, this information is used by Weave GitOps 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 also the dashboard. - -## Configuration - -In order to login via your OIDC provider, you need to 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 that has been setup for Weave GitOps in the issuer | | -| `clientSecret` | The client secret that has been setup for Weave GitOps in the issuer | | -| `redirectURL` | The redirect URL that has been setup 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 setup with a client ID/secret and the redirect URL of the dashboard. - -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' identity 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 it is recommended to read the [service account](service-account-permissions.mdx) and [user](user-permissions.mdx) permissions pages to understand which actions are needed for Weave GitOps to function correctly. - -## Customizing - -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, and the "email", and "groups" scopes are commonly used as unique identifiers in organisations. - -We use "offline_access" to allow 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" and "scopes" would be requested, in addition to "openid". - -### 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 we communicate 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= \ - --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, these should match your `kube-apiserver` configuration. - -### 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: - -#### Weave Gitops - -```yaml -envVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` - -#### Weave Gitops Enterprise - -```yaml -extraEnvVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` \ No newline at end of file diff --git a/website/versioned_docs/version-0.29.0/configuration/recommended-rbac-configuration.mdx b/website/versioned_docs/version-0.29.0/configuration/recommended-rbac-configuration.mdx deleted file mode 100644 index 03721cfdf3..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/recommended-rbac-configuration.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Recommended RBAC Configuration ---- - -This page summarises the contents of the [securing access to the dashboard](securing-access-to-the-dashboard.mdx), -[service account permissions](service-account-permissions.mdx) and [user permissions](user-permissions.mdx). They should be -read in addition to this page in order to understand the suggestions made here and -their ramifications. - -This page is purposefully vague as the intention is to give a broad idea of how -such a system could be implemented, not the specifics as that will be dependent -on your specific circumstances and goals. - -## Summary - -The general recommendation is to use OIDC and a small number of groups that -Weave GitOps can impersonate. - -OIDC is the recommended method for managing authentication as it 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](../guides/setting-up-dex.md)). - -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 set up - -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 readonly otherwise -* June and Jo, developers in team-A who should have read-only access to Weave GitOps - -You could then create 3 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'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 & 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 un-intended consequences (e.g. 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 readonly role to the readonly 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 ---- -``` - -
diff --git a/website/versioned_docs/version-0.29.0/configuration/securing-access-to-the-dashboard.mdx b/website/versioned_docs/version-0.29.0/configuration/securing-access-to-the-dashboard.mdx deleted file mode 100644 index b0f40ae381..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/securing-access-to-the-dashboard.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Securing access to the dashboard ---- - -## Dashboard Login - -There are 2 supported methods for logging in to the dashboard: -- [Login via an OIDC provider](../oidc-access) -- [Login via a cluster user account](../emergency-user) (not recommended) - -The recommended method is to integrate with an OIDC provider, -as this will let you control permissions for existing users and groups that have -already been configured to use OIDC. However, it is also possible to use the Emergency Cluster -User Account to login, if an OIDC provider is not available to use. -Both methods work with standard Kubernetes RBAC. diff --git a/website/versioned_docs/version-0.29.0/configuration/service-account-permissions.mdx b/website/versioned_docs/version-0.29.0/configuration/service-account-permissions.mdx deleted file mode 100644 index ef81eb1253..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/service-account-permissions.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Dashboard Runtime Permissions ---- - -# GitOps Dashboard Service Account Permissions - -:::danger Important -This doc covers the service account [permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -for the **Weave Gitops application** itself (ie. the permissions the Dashboard needs to work). -For the service account for the **cluster user** role (ie. for the user accessing the -GitOps Dashboard), see the page [here](user-permissions.mdx). -::: - -The default permissions of the service account 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 the users' permissions) -* Read the `cluster-user-auth` and `oidc-auth` secrets, which are the default secrets - to store the emergency cluster user account and OIDC configuration (see - [securing access to the dashboard](securing-access-to-the-dashboard.mdx)) - -## 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 -application (not the cluster) authenticates the user (either via the [emergency -cluster user](../emergency-user) credentials or OIDC) then makes calls to the Kube API 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 been granted permissions to get -deployments within the cluster then this will return them. The same occurs -within the application. This makes the proper configuration of the application's -permissions very important as, without proper restrictions it can impersonate -very powerful `users` or `groups`. For example, the `system:masters` is group -is generally bound to the `cluster-admin` role which can do anything. - -For more details of the permissions needed by the user or group see the -[user permissions](user-permissions.mdx) guide. - -### Configuring impersonation - -It is highly recommended that you limit which users and groups that 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 groups admin, dev-team -and qa-team (this also, implicitly disables the [emergency cluster user](../emergency-user)). - -Unfortunately not all OIDC providers support groups so 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](../guides/setting-up-dex.md) 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, if the emergency user is not -configured, that secret can be removed, or if the secret _is_ in use but renamed. diff --git a/website/versioned_docs/version-0.29.0/configuration/tls.md b/website/versioned_docs/version-0.29.0/configuration/tls.md deleted file mode 100644 index b9932d6ff6..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/tls.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: TLS and Certificates ---- - -## TLS configuration - -By default the dashboard will listen on 0.0.0.0:9001 with TLS disabled and -without exposing any external connection. - -Exposing services without TLS if not recommended. Without a certificate, a user -can't be sure they are using the right 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 ... -``` - -## cert-manager - -Install [cert-manager](../guides/cert-manager.md) and request a `Certificate` in -the `flux-system` namespace. Provide the name of secret associated with the -certificate to the weave-gitops-enterprise HelmRelease as described above. diff --git a/website/versioned_docs/version-0.29.0/configuration/user-permissions.mdx b/website/versioned_docs/version-0.29.0/configuration/user-permissions.mdx deleted file mode 100644 index 2ec436f633..0000000000 --- a/website/versioned_docs/version-0.29.0/configuration/user-permissions.mdx +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: User Permissions ---- -import TierLabel from "../_components/TierLabel"; - -This is an explanation of the [kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -needed by users/groups of the Weave GitOps application. As covered in -[service account permissions](service-account-permissions.mdx) -the primary way that the application interacts with the Kube API is via [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). -This means that the permissions granted to the users and groups that Weave GitOps -can impersonate determine the scope of actions that it can take within your cluster. - -At a minimum, a User should be bound to Role in the `flux-system` namespace (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 resources that Flux works with directly, including the one from TF-controller. - -| Api Group | Resources | Permissions | -| ------------------------------ | ----------------------------------------------------------------------- | ---------------- | -| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch | -| helm.toolkit.fluxcd.io | helmreleases | get, list, patch | -| source.toolkit.fluxcd.io | buckets, helmcharts, gitrepositories, helmrepositories, ocirepositories | get, list, patch | -| notification.toolkit.fluxcd.io | providers, alerts | get, list | -| infra.contrib.fluxcd.io | terraforms | get, list, patch | - -In order for Weave GitOps to be able to accurately display the state of Flux it -needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses. This is done using the -`get` and `list` permissions - -The `patch` permissions are used for 2 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 the annotations -of the resource. These features work the same way `flux suspend`, -`flux resume` and `flux reconcile` does on the CLI. - -### Resources managed via Flux - -| Api Group | Resources | Permissions | -|---------------------------|--------------------------------------------------------------------------------|------------------| -| "" | configmaps, secrets, pods, services, persistentvolumes, persistentvolumeclaims | get, list, watch | -| apps | deployments, replicasets, statefulsets | get, list, watch | -| batch | jobs, cronjobs | get, list, watch | -| autoscaling | horizontalpodautoscalers | get, list, watch | -| rbac.authorization.k8s.io | roles, clusterroles, rolebindings, clusterrolebindings | 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 - -The primary method by which Flux communicates the status of itself is by events, -these will show when reconciliations start and stop, whether they're successful -and information as to why they're not. - -## Weave GitOps Enterprise - -Weave GitOps Enterprise extends Weave GitOps OSS by adding more roles. These roles may need to be extended further in order to support certain use cases. Some of the most common use cases are described below. - -### Progressive delivery with Flagger - -Weave GitOps Enterprise integrates with Flagger in order to provide a view on progressive delivery deployments. This includes the ability to view all the resources that Flagger manages during its operation. The default ClusterRole `gitops-canaries-reader` includes the minimum permissions necessary for a user to be able to view canary object details, metric template object details and canary related events. - -When Flagger is configured to integrate with a service mesh such as Linkerd or Istio for the rollout, then this ClusterRole needs to be extended so that it can read the additional service mesh resources being generated by Flagger. Note that currently, in order to display service mesh or ingress related resources, we require `spec.provider` to be set in each canary resource. - -The following table provides a list of all the custom resources that Flagger generates grouped by provider: - -| Provider | API Group | Resource | -| --- | --- | --- | -| AppMesh | appmesh.k8s.aws | virtualnode | -| | appmesh.k8s.aws | virtualrouter | -| | appmesh.k8s.aws | virtualservice | -| Linkerd | split.smi-spec.io | trafficsplit | -| Istio | networking.istio.io | destinationrule | -| | networking.istio.io | virtualservice | -| Contour | projectcontour.io | httpproxy | -| Gloo | gateway.solo.io | routetable | -| | gloo.solo.io | upstream | -| Nginx | networking.k8s.io | ingress | -| Skipper | networking.k8s.io | ingress | -| Traefik | traefik.containo.us | traefikservice | -| Open Service Mesh | split.smi-spec.io | trafficsplit | -| Kuma | kuma.io | trafficroute | -| GatewayAPI | gateway.networking.k8s.io | httproute | - -For example, the following manifest shows how `gitops-canaries-reader` has been extended to allow the user for viewing TrafficSplit resources when Linkerd is used: - -
Expand to see example canary reader RBAC - -```yaml title="gitops-canaries-reader.yaml" -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitops-canaries-reader -rules: -- apiGroups: - - flagger.app - resources: - - canaries - - metrictemplates - verbs: - - get - - list -- apiGroups: - - "" - resources: - - events - verbs: - - get - - watch - - list -# Additional permissions for Linkerd resources are added below -- apiGroups: - - split.smi-spec.io - resources: - - trafficsplits - verbs: - - get - - list -``` - -
- -#### Setting up remote cluster permissions - -In order to view canaries in a remote cluster from the management cluster, you need to consider the following: -- The service account used to access the remote cluster needs to be able to list namespaces and custom resource definitions in the given cluster. It additionally needs to be able to impersonate users and groups. -- The user or group that logs in to the management cluster, needs appropriate permissions to certain resources of the remote cluster. - -For example, applying the following manifest on remote clusters, ensures that the `wego-admin` user will be able to view canary information from within the Weave GitOps Enterprise UI on the management cluster: - -
Expand to see example of remote cluster canary reader - -```yaml title="remote-cluster-service-user-rbac.yaml" -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: user-groups-impersonator -rules: - - apiGroups: [""] - resources: ["users", "groups"] - verbs: ["impersonate"] - - apiGroups: [""] - resources: ["namespaces"] - verbs: ["get", "list"] - - apiGroups: ["apiextensions.k8s.io"] - resources: ["customresourcedefinitions"] - verbs: ["get", "list"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: impersonate-user-groups -subjects: - - kind: ServiceAccount - name: remote-cluster-01 # Service account created in remote cluster - namespace: default -roleRef: - kind: ClusterRole - name: user-groups-impersonator - apiGroup: rbac.authorization.k8s.io ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: canary-reader -rules: - - apiGroups: [""] - resources: [ "events", "services" ] - verbs: [ "get", "list", "watch" ] - - apiGroups: [ "apps" ] - resources: [ "*" ] - verbs: [ "get", "list" ] - - apiGroups: [ "autoscaling" ] - resources: [ "*" ] - verbs: [ "get", "list" ] - - apiGroups: [ "flagger.app" ] - resources: [ "canaries", "metrictemplates"] - verbs: [ "get", "list", "watch" ] - - apiGroups: [ "helm.toolkit.fluxcd.io" ] - resources: [ "helmreleases" ] - verbs: [ "get", "list" ] - - apiGroups: [ "kustomize.toolkit.fluxcd.io" ] - resources: [ "kustomizations" ] - verbs: [ "get", "list" ] - - apiGroups: [ "source.toolkit.fluxcd.io" ] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list" ] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: read-canaries -subjects: -- kind: User - name: wego-admin # User logged in management cluster, impersonated via service account - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: canary-reader - apiGroup: rbac.authorization.k8s.io -``` - -
- -You may need to add more users/groups to the `read-canaries` ClusterRoleBinding to ensure additional users can view canary information from within the Weave GitOps Enterprise UI. diff --git a/website/versioned_docs/version-0.29.0/explorer/configuration.mdx b/website/versioned_docs/version-0.29.0/explorer/configuration.mdx index 862982c81f..a2249323c9 100644 --- a/website/versioned_docs/version-0.29.0/explorer/configuration.mdx +++ b/website/versioned_docs/version-0.29.0/explorer/configuration.mdx @@ -95,7 +95,7 @@ Query results are filtered honouring the access determined via RBAC. [GitopsClusters](../cluster-management/managing-clusters-without-capi.mdx/#connect-a-cluster) define the connection and security context that Explorer leverages to collect data from leaf clusters. Given that you have followed the indications -in [setup RBAC](../configuration/service-account-permissions.mdx), the GitopsCluster service account is able to impersonate any user or group. +in [setup RBAC](../enterprise/getting-started/install-enterprise.mdx#gitops-dashboard-service-account-permissions), the GitopsCluster service account is able to impersonate any user or group. :::tip diff --git a/website/versioned_docs/version-0.29.0/guides/setting-up-dex.md b/website/versioned_docs/version-0.29.0/guides/setting-up-dex.md deleted file mode 100644 index b2fcaf2258..0000000000 --- a/website/versioned_docs/version-0.29.0/guides/setting-up-dex.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Configuring OIDC with Dex and GitHub ---- - -In this guide we will show you how to enable users to login to the Weave GitOps dashboard by authenticating with their GitHub account. - -This example uses [Dex][tool-dex] and its GitHub connector, and assumes Weave GitOps has already been installed on a Kubernetes clusters. - -### Pre-requisites - -- A Kubernetes cluster such as [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) cluster running a -[Flux-supported version of Kubernetes](https://fluxcd.io/docs/installation/#prerequisites) -- Weave GitOps is [installed](../open-source/getting-started/install-OSS.mdx) and [TLS has been enabled](../configuration/tls.md). - -## What is Dex? - -[Dex][tool-dex] is an identity service that uses [OpenID Connect][oidc] to -drive authentication for other apps. - -Alternative solutions for identity and access management exist such as [Keycloak](https://www.keycloak.org/). - -[tool-dex]: https://dexidp.io/ -[oidc]: https://openid.net/connect/ - -## Create Dex namespace - -Create a namespace where Dex will be installed: - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: dex -``` - -## Add credentials - -There are a [lot of options][dex-connectors] available with Dex, in this guide we will -use the [GitHub connector][dex-github]. - -We can get a GitHub ClientID and Client secret by creating a -[new OAuth application][github-oauth]. - -![GitHub OAuth configuration](/img/guides/setting-up-dex/github-oauth-application.png) - -```bash -kubectl create secret generic github-client \ - --namespace=dex \ - --from-literal=client-id=${GITHUB_CLIENT_ID} \ - --from-literal=client-secret=${GITHUB_CLIENT_SECRET} -``` - -[dex-connectors]: https://dexidp.io/docs/connectors/ -[dex-github]: https://dexidp.io/docs/connectors/github/ -[github-oauth]: https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app - -## Deploy Dex - -As we did before, we can 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 -``` - -
- -:::note SSL certificate without cert manager -If we don't want to use cert manager, we can remove the related annotation and -use our predefined secret in the `tls` section. -::: - -An important part of the configuration is the `orgs` field on the GitHub -connector. - -```yaml -orgs: -- name: weaveworks - teams: - - team-a - - team-b - - QA -``` - -Here we can define groups under a GitHub organisation. In this example the -GitHub organisation is `weaveworks` and all members of the `team-a`, -`team-b`, and `QA` teams can authenticate. Group membership will be 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"] -``` - -
- -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 static user - -For 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" -``` - -A static user password can be generated with the `gitops` CLI: - -```bash -PASSWORD="" -echo -n $PASSWORD | gitops get bcrypt-hash -$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q -``` - -## OIDC login - -Using the "Login with OIDC Provider" button: - -![Login page](/img/guides/setting-up-dex/oidc-login.png) - -We have to authorize the GitHub OAuth application: - -![GitHub OAuth page](/img/guides/setting-up-dex/github-auth.png) - -After that, grant access to Dex: - -![Dex grant access](/img/guides/setting-up-dex/dex-auth.png) - -Now we are logged in with our GitHub user and we can see all resources we have -access to: - -![UI logged in](/img/guides/setting-up-dex/ui-logged-in.png) diff --git a/website/versioned_docs/version-0.29.0/open-source/getting-started/install-OSS.mdx b/website/versioned_docs/version-0.29.0/open-source/getting-started/install-OSS.mdx index 7760f3aae2..a4d8535143 100644 --- a/website/versioned_docs/version-0.29.0/open-source/getting-started/install-OSS.mdx +++ b/website/versioned_docs/version-0.29.0/open-source/getting-started/install-OSS.mdx @@ -176,7 +176,8 @@ Run the following command, which will create a `HelmRepository` and `HelmRelease This command stores a hash of a password. This is relatively safe for demo and testing purposes, but we strongly recommend using a more secure method of storing secrets (such as [Flux's SOPS integration][sops]) for production systems. -Our docs on [securing access to the dashboard][dash-access] provide additional guidance and alternative login methods. +Our docs on [securing access to the dashboard](../../enterprise/getting-started/install-enterprise.mdx#securing-access-to-the-dashboard) provide additional guidance and alternative login methods. + provide additional guidance and alternative login methods. ::: You will use the password you've just created when you've finished Weave GitOps Open Source installation and are ready to login to the dashboard UI. @@ -224,7 +225,6 @@ Now let's [explore the Weave GitOps Open Source UI](./ui-OSS.mdx). Then, we'll d [pat]: https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line [kubectl]: https://kubernetes.io/docs/tasks/tools/#kubectl [fl-install]: https://fluxcd.io/docs/installation/ -[dash-access]: ../../configuration/securing-access-to-the-dashboard.mdx [sops]: https://fluxcd.io/docs/guides/mozilla-sops/ [helm-repo]: https://fluxcd.io/flux/components/source/helmrepositories/#writing-a-helmrepository-spec [helm-rel]: https://fluxcd.io/flux/components/helm/helmreleases/ diff --git a/website/versioned_docs/version-0.29.0/open-source/getting-started/ui-OSS.mdx b/website/versioned_docs/version-0.29.0/open-source/getting-started/ui-OSS.mdx index 05babca9f8..781eb5f92d 100644 --- a/website/versioned_docs/version-0.29.0/open-source/getting-started/ui-OSS.mdx +++ b/website/versioned_docs/version-0.29.0/open-source/getting-started/ui-OSS.mdx @@ -37,8 +37,8 @@ First, expose the service running on the cluster with this command: kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001 ``` -Next, [open the dashboard](http://localhost:9001/) and login using either the [emergency cluster user](../../configuration/emergency-user.mdx) - or OIDC, based on your [configuration](../../configuration/securing-access-to-the-dashboard.mdx). +Next, [open the dashboard](http://localhost:9001/) and login using either the [emergency cluster user](../../enterprise/getting-started/install-enterprise.mdx#configuring-the-emergency-user) + or OIDC, based on your [configuration](../../enterprise/getting-started/install-enterprise.mdx#securing-access-to-the-dashboard)/. If you followed the example above, the emergency user will be configured with the username set to `admin`. This means that you can use “admin” as your user name, and the password that you set earlier during installation as `$PASSWORD`. ![Weave GitOps login screen](/img/dashboard-login.png) diff --git a/website/versioned_docs/version-0.29.0/terraform/using-terraform-templates.mdx b/website/versioned_docs/version-0.29.0/terraform/using-terraform-templates.mdx index 2a370d9fe2..1637a79125 100644 --- a/website/versioned_docs/version-0.29.0/terraform/using-terraform-templates.mdx +++ b/website/versioned_docs/version-0.29.0/terraform/using-terraform-templates.mdx @@ -14,7 +14,7 @@ This guide will show you how to use a template to create a Terraform resource in ## CLI Guide ### Prerequisites -- Install [Weave GitOps Enterprise](../enterprise/getting-started/install-enterprise.mdx) and [enable TLS](../configuration/tls.md). +- Install [Weave GitOps Enterprise](../enterprise/getting-started/install-enterprise.mdx) and [enable TLS](../enterprise/getting-started/install-enterprise.mdx#tls-configuration). - Install [Terraform Controller](../terraform/get-started-terraform.mdx). ### 1. Add a template to your cluster diff --git a/website/versioned_sidebars/version-0.29.0-sidebars.json b/website/versioned_sidebars/version-0.29.0-sidebars.json index 2f9dc99630..2e849cabd5 100644 --- a/website/versioned_sidebars/version-0.29.0-sidebars.json +++ b/website/versioned_sidebars/version-0.29.0-sidebars.json @@ -40,29 +40,6 @@ } ] }, - { - "type": "category", - "label": "Access Configuration", - "items": [ - "configuration/recommended-rbac-configuration", - { - "type": "category", - "label": "Securing Access to the Dashboard", - "collapsed": false, - "link": { - "type": "doc", - "id": "configuration/securing-access-to-the-dashboard" - }, - "items": [ - "configuration/oidc-access", - "configuration/emergency-user" - ] - }, - "configuration/service-account-permissions", - "configuration/user-permissions", - "configuration/tls" - ] - }, { "type": "category", "label": "Cluster Management", @@ -124,8 +101,6 @@ "type": "category", "label": "Guides", "items": [ - "guides/setting-up-dex", - "guides/cert-manager", "guides/displaying-custom-metadata", "guides/fluxga-upgrade" ]