From 5217600865e70c56af6f5f156193440a4a069cff Mon Sep 17 00:00:00 2001 From: Eneko Fernandez Date: Wed, 27 Dec 2023 18:21:16 +0100 Subject: [PATCH] Update enterprise getting started guide with Day 2 This update includes dividing the enterprise getting started guide into two days with Day 1 for onboarding platform engineers and Day 2 for expanding capabilities. It helps the users to follow the flow more intuitively. It also includes the enabling process of write access to Git and cluster management via Cluster API. The move towards a day-by-day guide contributes to a more structured and digestible learning process. Signed-off-by: Eneko Fernandez --- ...tall-enterprise-getting-started-expand.mdx | 380 +++++++++ ...tall-enterprise-getting-started-manual.mdx | 2 +- ...all-enterprise-getting-started-onboard.mdx | 377 +++++++++ .../install-enterprise-getting-started.mdx | 8 +- ...-enterprise-onboard-platform-engineers.mdx | 775 ------------------ .../getting-started/intro-enterprise.mdx | 4 +- website/sidebars.js | 3 +- 7 files changed, 763 insertions(+), 786 deletions(-) create mode 100644 website/docs/enterprise/getting-started/install-enterprise-getting-started-expand.mdx create mode 100644 website/docs/enterprise/getting-started/install-enterprise-getting-started-onboard.mdx delete mode 100644 website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started-expand.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started-expand.mdx new file mode 100644 index 0000000000..c13677a697 --- /dev/null +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started-expand.mdx @@ -0,0 +1,380 @@ +--- +title: Day 2 - Expand Capabilities +hide_title: true +toc_max_heading_level: 4 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import TierLabel from "@site/docs/_components/TierLabel"; +import AlphaWarning from "../../_components/_alpha_warning.mdx"; +import CurlCodeBlock from "../../_components/CurlCodeBlock"; +import oauthBitbucket from '/img/oauth-bitbucket.png'; +import oauthAzureDevOps from '/img/oauth-azure-devops.png'; +import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png'; + +# Day 2 - Expand Capabilities + +:::info What to expect +You are a Platform Engineer onboarded to Weave GitOps Enterprise to enable certain Platform Vertical like +Cluster Management. + +Use this guide to help you to add the capabilities with confidence. +::: + +## Enable Write Access to Git + +Weave GitOps Enterprise creates pull requests for adding resources. To do this, it needs to be able to write to the Git repository. +Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps. + + + +GitHub requires no additional configuration for OAuth git access + + + +Create a GitLab OAuth application that will request `api` permissions to create pull requests on your behalf. + +Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html). + +The application should have at least these scopes: + +- `api` +- `openid` +- `email` +- `profile` + +Add callback URLs to the application for each address the UI will be exposed on, e.g.: + +- `https://localhost:8000/oauth/gitlab` for port-forwarding and testing +- `https://git.example.com/oauth/gitlab` for production use + +Save your application, taking note of the **Client ID** and **Client Secret**. Save +them into the `git-provider-credentials` secret, along with: + +- `GIT_HOST_TYPES` to tell WGE that the host is gitlab +- `GITLAB_HOSTNAME` where the OAuth app is hosted + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="GITLAB_CLIENT_ID=13457" \ + --from-literal="GITLAB_CLIENT_SECRET=24680" \ + --from-literal="GITLAB_HOSTNAME=git.example.com" \ + --from-literal="GIT_HOST_TYPES=git.example.com=gitlab" +``` + + + + +Create a new [incoming application link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html) from +the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL +should be set to `$WGE_DASHBOARD_URL/oauth/bitbucketserver`. You will also need to select permissions for the application. The minimum set of +permissions needed for WGE to create pull requests on behalf of users is `Repositories - Write`. An example of configuring these settings is shown below. + +
+ + + +
Configuring a new incoming application link
+
+ + +Save your application and take note of the **Client ID** and **Client Secret**. Save +them into the `git-provider-credentials` secret, along with: + +- `GIT_HOST_TYPES` to tell WGE that the host is bitbucket-server +- `BITBUCKET_SERVER_HOSTNAME` where the OAuth app is hosted + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \ + --from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \ + --from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \ + --from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server" +``` + +If the secret is already present, use the following command to update it using your default editor: + +```bash +kubectl edit secret generic git-provider-credentials --namespace=flux-system +``` + +:::info + +If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: `GIT_HOST_TYPES=git.example.com:7990=bitbucket-server` + +::: + + + + + +Navigate to [VisualStudio](https://app.vsaex.visualstudio.com/app/register) and register a new application, as explained in the [docs](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops#1-register-your-app). Set the authorization callback URL and select which scopes to grant. Set the callback URL to `$WGE_DASHBOARD_URL/oauth/azuredevops`. + +Select the `Code (read and write)` scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below. + +
+ +
Creating a new application
+
+ +After creating your application, you will be presented with the application settings. Take note of the `App ID` and `Client Secret` values—you will use them to configure WGE. + +
+ +
Application settings
+
+ +In your cluster, create a secret named `git-provider-credentials` that contains the `App ID` and `Client Secret` values from the newly created application. + +**Replace values** in this snippet and run: + +```bash +kubectl create secret generic git-provider-credentials --namespace=flux-system \ + --from-literal="AZURE_DEVOPS_CLIENT_ID='App ID value'" \ + --from-literal="AZURE_DEVOPS_CLIENT_SECRET='Client Secret value'" +``` + +WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. +Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me. + + + + +## Enable Cluster Management via Cluster API + +// TODO should be at the getting started level and link to the other guides in depth. + +## Enable Policy via Weave Policy + +To install [Policy Agent](../../policy/intro.mdx) follow any of the following approaches: + + + + +You could configure this stage by using the following flags and examples: + +```bash + # install Policy Agent alongside Weave GitOps Enterprise + gitops bootstrap --components-extra="policy-agent" +``` + +For more information about the CLI configurations, check the below sections [here](#cli-configurations) + + + +[Policy agent](../../policy/intro.mdx) comes packaged with the WGE chart. To install it, set the following values: + +- `values.policy-agent.enabled`: set to true to install the agent with WGE +- `values.policy-agent.config.accountId`: organization name, used as identifier +- `values.policy-agent.config.clusterId`: unique identifier for the cluster + +Commit and push all the files + +```bash +git add clusters/management/weave-gitops-enterprise.yaml +git commit -m "Deploy Weave GitOps Enterprise" +git push +``` + +Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the `flux-system` namespace to verify all pods are running. + + + + +## Enable Infrastructure Management via Tf-Controller + + +## Advanced Topics + +### OIDC + +#### Customization + +For some OIDC configurations, you may need to customise the requested [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) or [claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims). + +The `oidcUsernamePrefix` and `oidcGroupsPrefix` work in the same way as the Kubernetes [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) command-line options, if you need them for Kubernetes, you will likely need them here. + +#### Scopes + +By default, the following scopes are requested: "openid","offline_access","email","groups". + +The "openid" scope is **mandatory** for OpenID auth and will be added if not provided. The "email" and "groups" scopes are commonly used as unique identifiers in organisations. + +"offline_access" allows us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid. You can, however, change the defaults. +```sh +kubectl create secret generic oidc-auth \ + --namespace flux-system \ + --from-literal=issuerURL=$oidc-issuer-url \ + --from-literal=clientID=$client-id \ + --from-literal=clientSecret=$client-secret \ + --from-literal=redirectURL=redirect-url \ + --from-literal=tokenDuration=token-duration \ + --from-literal=customScopes=custom,scopes +``` +The format for the `customScopes` key is a comma-separated list of scopes to request. In this case, "custom", "scopes", and "openid" would be requested. + +#### Claims + +By default, the following claims are parsed from the OpenID [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken) "email" and "groups". These are presented as the `user` and `groups` when WGE communicates with your Kubernetes API server. + +This is equivalent to [configuring](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server) your `kube-apiserver` with `--oidc-username-claim=email --oidc-groups-claim=groups`. + +Again, you can configure these from the `oidc-auth` `Secret`. + +```sh +kubectl create secret generic oidc-auth \ + --namespace flux-system \ + --from-literal=issuerURL=oidc-issuer-url \ + --from-literal=clientID=client-id \ + --from-literal=clientSecret=client-secret \ + --from-literal=redirectURL=redirect-url \ + --from-literal=tokenDuration=token-duration \ + --from-literal=claimUsername=sub \ + --from-literal=claimGroups=groups +``` +There are two separate configuration keys. You can override them separately. They should match your `kube-apiserver` configuration. + +### Cluster User + +#### Update Username or Password + +To change either the username or the password, recreate the `cluster-user-auth` +with the new details. + +Only one Cluster User can be created this way. To add more users, enable an OIDC provider. + +#### Update Permissions + +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. + +#### Remove It + +To remove the Cluster User as a login method, set the following values in the +[Helm Chart](../../references/helm-reference.md): + +```yaml +# +adminUser: + create: false +# +additionalArgs: +- --auth-methods=oidc +# +``` +:::caution If you are disabling an already existing Cluster User + +If you are disabling an already existing Cluster User, you will need to +manually delete the Kubernetes Secret and any User Roles that were created on +the cluster. + +::: + +### User Permissions + +This section discusses the [Kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +needed by Weave GitOps application users and groups. At a minimum, a User should be bound to a Role in the `flux-system` namespace—which is where +Flux stores its resources by default—with the following permissions: + +```yaml +rules: + # Flux Resources + - apiGroups: ["source.toolkit.fluxcd.io"] + resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] + verbs: [ "get", "list", "watch", "patch" ] + + - apiGroups: ["kustomize.toolkit.fluxcd.io"] + resources: [ "kustomizations" ] + verbs: [ "get", "list", "watch", "patch" ] + + - apiGroups: ["helm.toolkit.fluxcd.io"] + resources: [ "helmreleases" ] + verbs: [ "get", "list", "watch", "patch" ] + + - apiGroups: [ "notification.toolkit.fluxcd.io" ] + resources: [ "providers", "alerts" ] + verbs: [ "get", "list", "watch", "patch" ] + + - apiGroups: ["infra.contrib.fluxcd.io"] + resources: ["terraforms"] + verbs: [ "get", "list", "watch", "patch" ] + + # Read access for all other Kubernetes objects + - apiGroups: ["*"] + resources: ["*"] + verbs: [ "get", "list", "watch" ] +``` + +For a wider scope, the User can be bound to a ClusterRole with the same set. + +On top of this you can add other permissions to view WGE resources like `GitOpsSets` and `Templates`. + +#### Flux Resources + +The following table lists resources that Flux works with directly. + +| API Group | Resources | Permissions | +| ------------------------------ | ----------------------------------------------------------------------- | ---------------- | +| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch | +| helm.toolkit.fluxcd.io | Helm Releases | get, list, patch | +| source.toolkit.fluxcd.io | buckets, Helm charts, Git repositories, Helm repositories, OCI repositories | get, list, patch | +| notification.toolkit.fluxcd.io | providers, alerts | get, list | +| infra.contrib.fluxcd.io | [Terraform](https://github.com/weaveworks/tf-controller) | get, list, patch | + +Weave GitOps needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses before it can accurately display Flux state. The +`get` and `list` permissions facilitate this. + +The `patch` permissions are used for two features: to suspend and resume +reconciliation of a resource by modifying the 'spec' of a resource, +and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that `flux suspend`, +`flux resume`, and `flux reconcile` does on the CLI. + +#### Resources Managed via Flux + +| API Group | Resources | Permissions | +|---------------------------|--------------------------------------------------------------------------------|------------------| +| "" | configmaps, secrets, pods, services, persistent volumes, persistent volume claims | get, list, watch | +| apps | deployments, replica sets, stateful sets | get, list, watch | +| batch | jobs, cron jobs | get, list, watch | +| autoscaling | horizontal pod autoscalers | get, list, watch | +| rbac.authorization.k8s.io | roles, cluster roles, rolebindings, cluster role bindings | get, list, watch | +| networking.k8s.io | ingresses | get, list, watch | + +Weave GitOps reads basic resources so that it can monitor the effect that Flux has +on what's running. + +Reading `secrets` enables Weave GitOps to monitor the state of Helm releases +as that's where it stores the [state by default](https://helm.sh/docs/faq/changes_since_helm2/#secrets-as-the-default-storage-driver). +For clarity this these are the Helm release objects _not_ the Flux HelmRelease +resource (which are dealt with by the earlier section). + +#### Feedback from Flux + +Flux communicates the status of itself primarily via events. +These events will show when reconciliations start and stop, whether they're successful, +and information as to why they're not. + +### Customise the UI + +#### Login + +The label of the OIDC button on the login screen is configurable via a feature flag environment variable. +This can give your users a more familiar experience when logging in. + +Adjust the configuration in the Helm `values.yaml` file or the `spec.values` section of the Weave GitOps `HelmRelease` resource: + +```yaml +extraEnvVars: + - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL + value: "Login with ACME" +``` + + + diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx index 919fa974e5..a6dbd00f38 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx @@ -2,7 +2,7 @@ title: Manually hide_title: false pagination_prev: enterprise/getting-started/install-enterprise-getting-started -pagination_next: enterprise/getting-started/install-enterprise-onboard-platform-engineers +pagination_next: enterprise/getting-started/install-enterprise-getting-started-onboard toc_max_heading_level: 4 --- diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started-onboard.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started-onboard.mdx new file mode 100644 index 0000000000..a81c21d5ac --- /dev/null +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started-onboard.mdx @@ -0,0 +1,377 @@ +--- +title: Day 1 - Onboard Platform Engineers +hide_title: true +toc_max_heading_level: 4 +pagination_prev: enterprise/getting-started/install-enterprise-getting-started-onboard +pagination_next: enterprise/getting-started/install-enterprise-getting-started-expand +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import TierLabel from "@site/docs/_components/TierLabel"; +import AlphaWarning from "../../_components/_alpha_warning.mdx"; +import CurlCodeBlock from "../../_components/CurlCodeBlock"; +import oauthBitbucket from '/img/oauth-bitbucket.png'; +import oauthAzureDevOps from '/img/oauth-azure-devops.png'; +import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png'; + +# Day 1 - Onboard Platform Engineers + +:::info What to expect +You have [started with WGE](../install-enterprise-getting-started) and already familiar with its [bootstrapping workflow](../install-enterprise-getting-started/#bootstrapping). +You want to iterate your environment to onboard other Platform Engineers and finally Developers. + +Use this guide to adopt the recommendations that would enable you to do so with confidence. +::: + +## Authentication + +As a reminder, Weave GitOps Enterprise supports as authentication methods, Cluster User, that you have likely setup as part of the previous step, and OIDC. +OIDC is the recommended way for production, so take the time to set it up before onboarding other users. + +### Setup OIDC + +:::warning +Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted. +::: + +To login via your OIDC provider two steps are required: + +1. **Create a Kubernetes secret `oidc-auth` with the OIDC configuration**. This configuration consists of the following parameters: + +:::tip +For specific OIDC providers configuration (like Google or Azure) see [this guide](../../../guides/oidc/). +::: + +| Parameter | Description | Default | +| ------------------| -------------------------------------------------------------------------------------------------------------------------------- | --------- | +| `issuerURL` | The URL of the issuer; typically, the discovery URL without a path | | +| `clientID` | The client ID set up for Weave GitOps in the issuer | | +| `clientSecret` | The client secret set up for Weave GitOps in the issuer | | +| `redirectURL` | The redirect URL set up for Weave GitOps in the issuer—typically the dashboard URL, followed by `/oauth2/callback ` | | +| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | +| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | +| `oidcUsernamePrefix` | The prefix added to users when impersonating API calls to the Kubernetes API, equivalent to --oidc-username-prefix | | +| `oidcGroupsPrefix` | The prefix added to groups when impersonating API calls to the Kubernetes API, equivalent to --oidc-groups-prefix | | + +Ensure that your OIDC provider has been set up with a client ID/secret and the dashboard's redirect URL. + +2. **Configure WGE to use OIDC** + + + + +Execute `gitops bootstrap auth` to complete the task: + +```bash +# Add OIDC configuration to your environment +gitops bootstrap auth --type=oidc --client-id="client-id" \ + --client-secret="client-secret" \ + --discovery-url="discovery-url" +``` + + + + +1. Create a Kubernetes secret `oidc-auth` with the OIDC configuration + +```bash +kubectl create secret generic oidc-auth \ + --namespace flux-system \ + --from-literal=issuerURL="oidc-issuer-url" \ + --from-literal=clientID="client-id" \ + --from-literal=clientSecret="client-secret" \ + --from-literal=redirectURL="redirect-url" \ + --from-literal=tokenDuration="token-duration" +``` + +2. Configure WGE to use OIDC + +```yaml +--- +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: weave-gitops-enterprise + namespace: flux-system +spec: + # ... other spec components + values: + config: + oidc: + clientCredentialsSecret: oidc-auth + enabled: true + issuerURL: "oidc-issuer-url" + redirectURL: "redirect-url" +``` + + + + +Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in. + +:::tip Running into issues setting up OIDC? +Use [`gitops check oidc-config`](../../../references/cli-reference/gitops_check_oidc-config/) command to help you troubleshoot your OIDC configuration. +::: + +![Weave GitOps Enterprise Login](./imgs/wge-login-ui.png) + + +See [Advanced Topics](#advanced-topics) for other OIDC topics like customise scopes. + +## Authorization + +Weave GitOps Enterprise works with standard [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for authorization of: + +- **Weave GitOps Users:** previously authenticated via either OIDC or Cluster User. +- **Weave GitOps Service Account:** which talks to Kubernetes for user operations via [Impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). +- **Flux Service Accounts:** which talks to Kubernetes for deployments operations. + +### RBAC for OIDC Users + +During [getting started](../install-enterprise-getting-started/) you have created the default authorization clusters for `Cluser User`, `Weave GitOps Service Account` +and `Flux Service Accounts` but not for OIDC users. You could setup Authorization for OIDC users by defining and deploying the RBAC rules. + +#### Define the Rules + +RBAC rules are highly context-dependent and there is no one-size fits all. You would need to take the time with your Security organisation on defining them. + +We provide you with the following RBAC Configuration as inspirational to get you conversations started. It is purposefully vague as we intend to give a +broad idea of how to implement such a system. The specifics will dependent on your circumstances and goals. + +
+Expand to see a Example RBAC Configuration + +Our general recommendation is to use OIDC and a small number of groups that Weave GitOps can impersonate. + +Configuring Weave GitOps to impersonate Kubernetes groups rather than users has the following benefits: +* A user's permissions for impersonation by Weave GitOps can be separate from +any other permissions that they may or may not have within the cluster. +* Users do not have to be individually managed within the cluster and can have +their permissions managed together. + +**Design** + +Assume that your company has the following people in OIDC: +* Aisha, a cluster admin, who should have full admin access to Weave GitOps +* Brian, lead of Team-A, who should have admin permissions to their team's +namespace in Weave GitOps and read-only otherwise +* June and Jo, developers in Team-A who should have read-only access to Weave GitOps + +You can then create three groups: + +* `wego-admin` + - Bound to the `ClusterRole`, created by Helm, `wego-admin-cluster-role` + - Aisha is the only member +* `wego-team-a-admin` + - Bound to a `Role`, using the same permissions as `wego-admin-role`, created + in Team-A's namespace + - Brian and Aisha are members +* `wego-readonly` + - Bound to a `ClusterRole` that matches `wego-admin-cluster-role` but with + no `patch` permissions. + - Aisha, Brian, June and Jo are all members + +**Code** + +```yaml +# Admin cluster role +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: wego-admin-cluster-role +rules: + - apiGroups: [""] + resources: ["secrets", "pods" ] + verbs: [ "get", "list" ] + - apiGroups: ["apps"] + resources: [ "deployments", "replicasets"] + verbs: [ "get", "list" ] + - apiGroups: ["kustomize.toolkit.fluxcd.io"] + resources: [ "kustomizations" ] + verbs: [ "get", "list", "patch" ] + - apiGroups: ["helm.toolkit.fluxcd.io"] + resources: [ "helmreleases" ] + verbs: [ "get", "list", "patch" ] + - apiGroups: ["source.toolkit.fluxcd.io"] + resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] + verbs: [ "get", "list", "patch" ] + - apiGroups: [""] + resources: ["events"] + verbs: ["get", "watch", "list"] +--- +# Read-only cluster role +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: wego-readonly-role +rules: + # All the 'patch' permissions have been removed + - apiGroups: [""] + resources: ["secrets", "pods" ] + verbs: [ "get", "list" ] + - apiGroups: ["apps"] + resources: [ "deployments", "replicasets"] + verbs: [ "get", "list" ] + - apiGroups: ["kustomize.toolkit.fluxcd.io"] + resources: [ "kustomizations" ] + verbs: [ "get", "list" ] + - apiGroups: ["helm.toolkit.fluxcd.io"] + resources: [ "helmreleases" ] + verbs: [ "get", "list" ] + - apiGroups: ["source.toolkit.fluxcd.io"] + resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] + verbs: [ "get", "list" ] + - apiGroups: [""] + resources: ["events"] + verbs: ["get", "watch", "list"] +--- +# Bind the cluster admin role to the wego-admin group +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: wego-cluster-admin +subjects: +- kind: Group + name: wego-admin # only Aisha is a member + apiGroup: rbac.authorization.k8s.io +roleRef: + kind: ClusterRole + name: wego-admin-cluster-role + apiGroup: rbac.authorization.k8s.io +--- +# Bind the admin role in the team-a namespace for the wego-team-a-admin group +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: wego-team-a-admin-role + namespace: team-a +subjects: +- kind: Group + name: wego-team-a-admin # Aisha & Brian are members + apiGroup: rbac.authorization.k8s.io +roleRef: + # Use the cluster role to set rules, just bind them in the team-a namespace + kind: ClusterRole + name: wego-admin-role + apiGroup: rbac.authorization.k8s.io +--- +# Bind the read-only role to the read-only group +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: wego-readonly-role +subjects: +- kind: Group + name: wego-readonly # Everyone is a member + apiGroup: rbac.authorization.k8s.io +roleRef: + kind: ClusterRole + name: wego-readonly-role + apiGroup: rbac.authorization.k8s.io +--- +``` + +:::caution Using OIDC for cluster and Weave GitOps Authentication +If the same OIDC provider is used to authenticate a user with the cluster +itself (e.g. for use with `kubectl`) and to Weave GitOps then, depending +on OIDC configuration, they may end up with the super-set of their permissions +from Weave GitOps and any other permissions granted to them. + +This can lead to unintended consequences, like viewing `secrets`. To avoid +this, OIDC providers will often let you configure which groups are returned +to which clients. The Weave GitOps groups should not be returned to the +cluster client (and vice versa). +::: + + + +
+ +#### Deploy them via `/bases` + +Once you have the rules defined, you want to ensure they are available in your environment. The `bases` pattern is a useful approach +to easily achieve this. It works as follows: + + + + +:::caution + +Not yet supported but planned as part of https://github.com/weaveworks/weave-gitops-enterprise/issues/3618 + +::: + + + + +1. Create a folder in your Git repo in path like `clusters/bases`. +2. Add your RBAC resources into the folder `clusters/bases/rbac`. +3. Create a folder `clusters/management` adding the following `Kustomization`: + +```yaml title="clusters/management/clusters-bases-kustomization.yaml" +apiVersion: kustomize.toolkit.fluxcd.io/v1 +kind: Kustomization +metadata: + name: clusters-bases-kustomization + namespace: flux-system +spec: + interval: 10m0s + path: clusters/bases + prune: true + sourceRef: + kind: GitRepository + name: flux-system +``` + +Save these two files in your Git repository, then commit and push. Flux will deploy the kustomization and the RBAC +resources will be created. + + + + +## Access the dashboard + +During [getting started](../install-enterprise-getting-started/) you have accessed the dashboard via its non-TLS ClusterIP service +which is not enough to onboard other users. Use this section to configure the dashboard access in a secured and reliable manner. + +### Configure Dashboard Access + +Weave GitOps Enterprise dashboard is available by default via ClusterIP service. You could use the `port-forward` command +output as part of the bootstrapping session. Other networking configurations could be achieved by +modifying the `service` or `ingress` in the `HelmRelease` values: + +```yaml +--- +apiVersion: helm.toolkit.fluxcd.io/v2beta1 +kind: HelmRelease +metadata: + name: weave-gitops-enterprise + namespace: flux-system +spec: + values: + service: # update to meet your needs + ... + ingress: # update to meet your needs + ... +``` +### Configure TLS + +// TODO review + +If you're using an ingress controller to terminate TLS you can disable it in the Helm release: + +```yaml + values: + tls: + enabled: false +``` + +Other ingress configuration changes can be made via the ingress configuration + +```yaml + values: + ingress: + enabled: true + ... other parameters specific to the ingress type ... +``` \ No newline at end of file diff --git a/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx b/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx index 8158bfcfa9..fd65fef20b 100644 --- a/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise-getting-started.mdx @@ -2,7 +2,7 @@ title: Day 0 - Getting Started hide_title: true pagination_prev: enterprise/getting-started/intro-enterprise -pagination_next: enterprise/getting-started/install-enterprise-onboard-platform-engineers +pagination_next: enterprise/getting-started/install-enterprise-getting-started-onboard toc_max_heading_level: 4 --- @@ -157,9 +157,3 @@ Access your browser on http://localhost:8000 Login with the user credentials that you have configured as part of the bootstrapping session. ![Weave GitOps Enterprise Cluster](./imgs/wge-clusters-ui.png) - -## Next Steps - -Continue with [**Onboard Platform Engineers**](../install-enterprise-onboard-platform-engineers) to harden your setup to onboard other Platform Engineers. -Other Platform Engineers setup any WGE capabilities for your devs. - diff --git a/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx b/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx deleted file mode 100644 index 2ab14f6700..0000000000 --- a/website/docs/enterprise/getting-started/install-enterprise-onboard-platform-engineers.mdx +++ /dev/null @@ -1,775 +0,0 @@ ---- -title: Day 1 - Onboard Platform Engineers -hide_title: true -toc_max_heading_level: 4 ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; -import TierLabel from "@site/docs/_components/TierLabel"; -import AlphaWarning from "../../_components/_alpha_warning.mdx"; -import CurlCodeBlock from "../../_components/CurlCodeBlock"; -import oauthBitbucket from '/img/oauth-bitbucket.png'; -import oauthAzureDevOps from '/img/oauth-azure-devops.png'; -import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png'; - -# Day 1 - Onboard Platform Engineers - -:::info What to expect -You have [started with WGE](../install-enterprise-getting-started) and already familiar with its [bootstrapping workflow](../install-enterprise-getting-started/#bootstrapping). -You want to iterate your environment to onboard other Platform Engineers and finally Developers. - -Use this guide to adopt the recommendations that would enable you to do so with confidence. -::: - -## Authentication - -As a reminder, Weave GitOps Enterprise supports as authentication methods, Cluster User, that you have likely setup as part of the previous step, and OIDC. -OIDC is the recommended way for production, so take the time to set it up before onboarding other users. - -### Setup OIDC - -:::warning -Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted. -::: - -To login via your OIDC provider two steps are required: - -1. **Create a Kubernetes secret `oidc-auth` with the OIDC configuration**. This configuration consists of the following parameters: - -:::tip -For specific OIDC providers configuration (like Google or Azure) see [this guide](../../../guides/oidc/). -::: - -| Parameter | Description | Default | -| ------------------| -------------------------------------------------------------------------------------------------------------------------------- | --------- | -| `issuerURL` | The URL of the issuer; typically, the discovery URL without a path | | -| `clientID` | The client ID set up for Weave GitOps in the issuer | | -| `clientSecret` | The client secret set up for Weave GitOps in the issuer | | -| `redirectURL` | The redirect URL set up for Weave GitOps in the issuer—typically the dashboard URL, followed by `/oauth2/callback ` | | -| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | -| `tokenDuration` | The time duration that the ID Token will remain valid after successful authentication | "1h0m0s" | -| `oidcUsernamePrefix` | The prefix added to users when impersonating API calls to the Kubernetes API, equivalent to --oidc-username-prefix | | -| `oidcGroupsPrefix` | The prefix added to groups when impersonating API calls to the Kubernetes API, equivalent to --oidc-groups-prefix | | - -Ensure that your OIDC provider has been set up with a client ID/secret and the dashboard's redirect URL. - -2. **Configure WGE to use OIDC** - - - - -Execute `gitops bootstrap auth` to complete the task: - -```bash -# Add OIDC configuration to your environment -gitops bootstrap auth --type=oidc --client-id="client-id" \ - --client-secret="client-secret" \ - --discovery-url="discovery-url" -``` - - - - -1. Create a Kubernetes secret `oidc-auth` with the OIDC configuration - -```bash -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL="oidc-issuer-url" \ - --from-literal=clientID="client-id" \ - --from-literal=clientSecret="client-secret" \ - --from-literal=redirectURL="redirect-url" \ - --from-literal=tokenDuration="token-duration" -``` - -2. Configure WGE to use OIDC - -```yaml ---- -apiVersion: helm.toolkit.fluxcd.io/v2beta1 -kind: HelmRelease -metadata: - name: weave-gitops-enterprise - namespace: flux-system -spec: - # ... other spec components - values: - config: - oidc: - clientCredentialsSecret: oidc-auth - enabled: true - issuerURL: "oidc-issuer-url" - redirectURL: "redirect-url" -``` - - - - -Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in. - -:::tip Running into issues setting up OIDC? -Use [`gitops check oidc-config`](../../../references/cli-reference/gitops_check_oidc-config/) command to help you troubleshoot your OIDC configuration. -::: - -![Weave GitOps Enterprise Login](./imgs/wge-login-ui.png) - - -See [Advanced Topics](#advanced-topics) for other OIDC topics like customise scopes. - -## Authorization - -Weave GitOps Enterprise works with standard [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for authorization of: - -- **Weave GitOps Users:** previously authenticated via either OIDC or Cluster User. -- **Weave GitOps Service Account:** which talks to Kubernetes for user operations via [Impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). -- **Flux Service Accounts:** which talks to Kubernetes for deployments operations. - -### RBAC for OIDC Users - -During [getting started](../install-enterprise-getting-started/) you have created the default authorization clusters for `Cluser User`, `Weave GitOps Service Account` -and `Flux Service Accounts` but not for OIDC users. You could setup Authorization for OIDC users by defining and deploying the RBAC rules. - -#### Define the Rules - -RBAC rules are highly context-dependent and there is no one-size fits all. You would need to take the time with your Security organisation on defining them. - -We provide you with the following RBAC Configuration as inspirational to get you conversations started. It is purposefully vague as we intend to give a -broad idea of how to implement such a system. The specifics will dependent on your circumstances and goals. - -
-Expand to see a Example RBAC Configuration - -Our general recommendation is to use OIDC and a small number of groups that Weave GitOps can impersonate. - -Configuring Weave GitOps to impersonate Kubernetes groups rather than users has the following benefits: -* A user's permissions for impersonation by Weave GitOps can be separate from -any other permissions that they may or may not have within the cluster. -* Users do not have to be individually managed within the cluster and can have -their permissions managed together. - -**Design** - -Assume that your company has the following people in OIDC: -* Aisha, a cluster admin, who should have full admin access to Weave GitOps -* Brian, lead of Team-A, who should have admin permissions to their team's -namespace in Weave GitOps and read-only otherwise -* June and Jo, developers in Team-A who should have read-only access to Weave GitOps - -You can then create three groups: - -* `wego-admin` - - Bound to the `ClusterRole`, created by Helm, `wego-admin-cluster-role` - - Aisha is the only member -* `wego-team-a-admin` - - Bound to a `Role`, using the same permissions as `wego-admin-role`, created - in Team-A's namespace - - Brian and Aisha are members -* `wego-readonly` - - Bound to a `ClusterRole` that matches `wego-admin-cluster-role` but with - no `patch` permissions. - - Aisha, Brian, June and Jo are all members - -**Code** - -```yaml -# Admin cluster role -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: wego-admin-cluster-role -rules: - - apiGroups: [""] - resources: ["secrets", "pods" ] - verbs: [ "get", "list" ] - - apiGroups: ["apps"] - resources: [ "deployments", "replicasets"] - verbs: [ "get", "list" ] - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list", "patch" ] - - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] ---- -# Read-only cluster role -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: wego-readonly-role -rules: - # All the 'patch' permissions have been removed - - apiGroups: [""] - resources: ["secrets", "pods" ] - verbs: [ "get", "list" ] - - apiGroups: ["apps"] - resources: [ "deployments", "replicasets"] - verbs: [ "get", "list" ] - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list" ] - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list" ] - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list" ] - - apiGroups: [""] - resources: ["events"] - verbs: ["get", "watch", "list"] ---- -# Bind the cluster admin role to the wego-admin group -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: wego-cluster-admin -subjects: -- kind: Group - name: wego-admin # only Aisha is a member - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: wego-admin-cluster-role - apiGroup: rbac.authorization.k8s.io ---- -# Bind the admin role in the team-a namespace for the wego-team-a-admin group -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: - name: wego-team-a-admin-role - namespace: team-a -subjects: -- kind: Group - name: wego-team-a-admin # Aisha & Brian are members - apiGroup: rbac.authorization.k8s.io -roleRef: - # Use the cluster role to set rules, just bind them in the team-a namespace - kind: ClusterRole - name: wego-admin-role - apiGroup: rbac.authorization.k8s.io ---- -# Bind the read-only role to the read-only group -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: wego-readonly-role -subjects: -- kind: Group - name: wego-readonly # Everyone is a member - apiGroup: rbac.authorization.k8s.io -roleRef: - kind: ClusterRole - name: wego-readonly-role - apiGroup: rbac.authorization.k8s.io ---- -``` - -:::caution Using OIDC for cluster and Weave GitOps Authentication -If the same OIDC provider is used to authenticate a user with the cluster -itself (e.g. for use with `kubectl`) and to Weave GitOps then, depending -on OIDC configuration, they may end up with the super-set of their permissions -from Weave GitOps and any other permissions granted to them. - -This can lead to unintended consequences, like viewing `secrets`. To avoid -this, OIDC providers will often let you configure which groups are returned -to which clients. The Weave GitOps groups should not be returned to the -cluster client (and vice versa). -::: - - - -
- -#### Deploy them via `/bases` - -Once you have the rules defined, you want to ensure they are available in your environment. The `bases` pattern is a useful approach -to easily achieve this. It works as follows: - - - - -:::caution - -Not yet supported but planned as part of https://github.com/weaveworks/weave-gitops-enterprise/issues/3618 - -::: - - - - -1. Create a folder in your Git repo in path like `clusters/bases`. -2. Add your RBAC resources into the folder `clusters/bases/rbac`. -3. Create a folder `clusters/management` adding the following `Kustomization`: - -```yaml title="clusters/management/clusters-bases-kustomization.yaml" -apiVersion: kustomize.toolkit.fluxcd.io/v1 -kind: Kustomization -metadata: - name: clusters-bases-kustomization - namespace: flux-system -spec: - interval: 10m0s - path: clusters/bases - prune: true - sourceRef: - kind: GitRepository - name: flux-system -``` - -Save these two files in your Git repository, then commit and push. Flux will deploy the kustomization and the RBAC -resources will be created. - - - - - - - -## Access the dashboard - -During [getting started](../install-enterprise-getting-started/) you have accessed the dashboard via its non-TLS ClusterIP service -which is not enough to onboard other users. Use this section to configure the dashboard access in a secured and reliable manner. - -### Configure Dashboard Access - -Weave GitOps Enterprise dashboard is available by default via ClusterIP service. You could use the `port-forward` command -output as part of the bootstrapping session. Other networking configurations could be achieved by -modifying the `service` or `ingress` in the `HelmRelease` values: - -```yaml ---- -apiVersion: helm.toolkit.fluxcd.io/v2beta1 -kind: HelmRelease -metadata: - name: weave-gitops-enterprise - namespace: flux-system -spec: - values: - service: # update to meet your needs - ... - ingress: # update to meet your needs - ... -``` -### Configure TLS - -// TODO review - -If you're using an ingress controller to terminate TLS you can disable it in the Helm release: - -```yaml - values: - tls: - enabled: false -``` - -Other ingress configuration changes can be made via the ingress configuration - -```yaml - values: - ingress: - enabled: true - ... other parameters specific to the ingress type ... -``` - -## Expand WGE Capabilities - -During [getting started](../install-enterprise-getting-started/) you have installed Flux and WGE which allows you to deploy and -view Flux Applications. Expand your environment capabilities by following the section below. - -### Enable Write Access to Git - -Weave GitOps Enterprise creates pull requests for adding resources. To do this, it needs to be able to write to the Git repository. -Here we provide guidance for GitHub, GitLab, BitBucket Server, and Azure DevOps. - - - -GitHub requires no additional configuration for OAuth git access - - - -Create a GitLab OAuth application that will request `api` permissions to create pull requests on your behalf. - -Follow the [GitLab docs](https://docs.gitlab.com/ee/integration/oauth_provider.html). - -The application should have at least these scopes: - -- `api` -- `openid` -- `email` -- `profile` - -Add callback URLs to the application for each address the UI will be exposed on, e.g.: - -- `https://localhost:8000/oauth/gitlab` for port-forwarding and testing -- `https://git.example.com/oauth/gitlab` for production use - -Save your application, taking note of the **Client ID** and **Client Secret**. Save -them into the `git-provider-credentials` secret, along with: - -- `GIT_HOST_TYPES` to tell WGE that the host is gitlab -- `GITLAB_HOSTNAME` where the OAuth app is hosted - -**Replace values** in this snippet and run: - -```bash -kubectl create secret generic git-provider-credentials --namespace=flux-system \ - --from-literal="GITLAB_CLIENT_ID=13457" \ - --from-literal="GITLAB_CLIENT_SECRET=24680" \ - --from-literal="GITLAB_HOSTNAME=git.example.com" \ - --from-literal="GIT_HOST_TYPES=git.example.com=gitlab" -``` - - - - -Create a new [incoming application link](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html) from -the BitBucket administration dashboard. You will be asked to enter a unique name and the redirect URL for the external application. The redirect URL -should be set to `$WGE_DASHBOARD_URL/oauth/bitbucketserver`. You will also need to select permissions for the application. The minimum set of -permissions needed for WGE to create pull requests on behalf of users is `Repositories - Write`. An example of configuring these settings is shown below. - -
- - - -
Configuring a new incoming application link
-
- - -Save your application and take note of the **Client ID** and **Client Secret**. Save -them into the `git-provider-credentials` secret, along with: - -- `GIT_HOST_TYPES` to tell WGE that the host is bitbucket-server -- `BITBUCKET_SERVER_HOSTNAME` where the OAuth app is hosted - -**Replace values** in this snippet and run: - -```bash -kubectl create secret generic git-provider-credentials --namespace=flux-system \ - --from-literal="BITBUCKET_SERVER_CLIENT_ID=13457" \ - --from-literal="BITBUCKET_SERVER_CLIENT_SECRET=24680" \ - --from-literal="BITBUCKET_SERVER_HOSTNAME=git.example.com" \ - --from-literal="GIT_HOST_TYPES=git.example.com=bitbucket-server" -``` - -If the secret is already present, use the following command to update it using your default editor: - -```bash -kubectl edit secret generic git-provider-credentials --namespace=flux-system -``` - -:::info - -If BitBucket Server is running on the default port (7990), make sure you include the port number in the values of the secret. For example: `GIT_HOST_TYPES=git.example.com:7990=bitbucket-server` - -::: - - - - - -Navigate to [VisualStudio](https://app.vsaex.visualstudio.com/app/register) and register a new application, as explained in the [docs](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops#1-register-your-app). Set the authorization callback URL and select which scopes to grant. Set the callback URL to `$WGE_DASHBOARD_URL/oauth/azuredevops`. - -Select the `Code (read and write)` scope from the list. This is necessary so that WGE can create pull requests on behalf of users. An example of configuring these settings is shown below. - -
- -
Creating a new application
-
- -After creating your application, you will be presented with the application settings. Take note of the `App ID` and `Client Secret` values—you will use them to configure WGE. - -
- -
Application settings
-
- -In your cluster, create a secret named `git-provider-credentials` that contains the `App ID` and `Client Secret` values from the newly created application. - -**Replace values** in this snippet and run: - -```bash -kubectl create secret generic git-provider-credentials --namespace=flux-system \ - --from-literal="AZURE_DEVOPS_CLIENT_ID='App ID value'" \ - --from-literal="AZURE_DEVOPS_CLIENT_SECRET='Client Secret value'" -``` - -WGE is now configured to ask users for authorization the next time a pull request must be created as part of using a template. -Note that each user can view and manage which applications they have authorized by navigating to https://app.vsaex.visualstudio.com/me. - - - - -### Enable Cluster Management via Cluster API - -TBA - -### Enable Policy via Weave Policy - -To install [Policy Agent](../../policy/intro.mdx) follow any of the following approaches: - - - - -You could configure this stage by using the following flags and examples: - -```bash - # install Policy Agent alongside Weave GitOps Enterprise - gitops bootstrap --components-extra="policy-agent" -``` - -For more information about the CLI configurations, check the below sections [here](#cli-configurations) - - - -[Policy agent](../../policy/intro.mdx) comes packaged with the WGE chart. To install it, set the following values: - -- `values.policy-agent.enabled`: set to true to install the agent with WGE -- `values.policy-agent.config.accountId`: organization name, used as identifier -- `values.policy-agent.config.clusterId`: unique identifier for the cluster - -Commit and push all the files - -```bash -git add clusters/management/weave-gitops-enterprise.yaml -git commit -m "Deploy Weave GitOps Enterprise" -git push -``` - -Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the `flux-system` namespace to verify all pods are running. - - - - -### Enable Infrastructure Management via Tf-Controller - - - -## Advanced Topics - -### OIDC - -#### Customization - -For some OIDC configurations, you may need to customise the requested [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) or [claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims). - -The `oidcUsernamePrefix` and `oidcGroupsPrefix` work in the same way as the Kubernetes [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) command-line options, if you need them for Kubernetes, you will likely need them here. - -#### Scopes - -By default, the following scopes are requested: "openid","offline_access","email","groups". - -The "openid" scope is **mandatory** for OpenID auth and will be added if not provided. The "email" and "groups" scopes are commonly used as unique identifiers in organisations. - -"offline_access" allows us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid. You can, however, change the defaults. -```sh -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL=$oidc-issuer-url \ - --from-literal=clientID=$client-id \ - --from-literal=clientSecret=$client-secret \ - --from-literal=redirectURL=redirect-url \ - --from-literal=tokenDuration=token-duration \ - --from-literal=customScopes=custom,scopes -``` -The format for the `customScopes` key is a comma-separated list of scopes to request. In this case, "custom", "scopes", and "openid" would be requested. - -#### Claims - -By default, the following claims are parsed from the OpenID [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken) "email" and "groups". These are presented as the `user` and `groups` when WGE communicates with your Kubernetes API server. - -This is equivalent to [configuring](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server) your `kube-apiserver` with `--oidc-username-claim=email --oidc-groups-claim=groups`. - -Again, you can configure these from the `oidc-auth` `Secret`. - -```sh -kubectl create secret generic oidc-auth \ - --namespace flux-system \ - --from-literal=issuerURL=oidc-issuer-url \ - --from-literal=clientID=client-id \ - --from-literal=clientSecret=client-secret \ - --from-literal=redirectURL=redirect-url \ - --from-literal=tokenDuration=token-duration \ - --from-literal=claimUsername=sub \ - --from-literal=claimGroups=groups -``` -There are two separate configuration keys. You can override them separately. They should match your `kube-apiserver` configuration. - -### Cluster User - -#### Update Username or Password - -To change either the username or the password, recreate the `cluster-user-auth` -with the new details. - -Only one Cluster User can be created this way. To add more users, enable an OIDC provider. - -#### Update Permissions - -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. - -#### Remove It - -To remove the Cluster User as a login method, set the following values in the -[Helm Chart](../../references/helm-reference.md): - -```yaml -# -adminUser: - create: false -# -additionalArgs: -- --auth-methods=oidc -# -``` -:::caution If you are disabling an already existing Cluster User - -If you are disabling an already existing Cluster User, you will need to -manually delete the Kubernetes Secret and any User Roles that were created on -the cluster. - -::: - -### User Permissions - -This section discusses the [Kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) -needed by Weave GitOps application users and groups. At a minimum, a User should be bound to a Role in the `flux-system` namespace—which is where -Flux stores its resources by default—with the following permissions: - -```yaml -rules: - # Flux Resources - - apiGroups: ["source.toolkit.fluxcd.io"] - resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["kustomize.toolkit.fluxcd.io"] - resources: [ "kustomizations" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["helm.toolkit.fluxcd.io"] - resources: [ "helmreleases" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: [ "notification.toolkit.fluxcd.io" ] - resources: [ "providers", "alerts" ] - verbs: [ "get", "list", "watch", "patch" ] - - - apiGroups: ["infra.contrib.fluxcd.io"] - resources: ["terraforms"] - verbs: [ "get", "list", "watch", "patch" ] - - # Read access for all other Kubernetes objects - - apiGroups: ["*"] - resources: ["*"] - verbs: [ "get", "list", "watch" ] -``` - -For a wider scope, the User can be bound to a ClusterRole with the same set. - -On top of this you can add other permissions to view WGE resources like `GitOpsSets` and `Templates`. - -#### Flux Resources - -The following table lists resources that Flux works with directly. - -| API Group | Resources | Permissions | -| ------------------------------ | ----------------------------------------------------------------------- | ---------------- | -| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch | -| helm.toolkit.fluxcd.io | Helm Releases | get, list, patch | -| source.toolkit.fluxcd.io | buckets, Helm charts, Git repositories, Helm repositories, OCI repositories | get, list, patch | -| notification.toolkit.fluxcd.io | providers, alerts | get, list | -| infra.contrib.fluxcd.io | [Terraform](https://github.com/weaveworks/tf-controller) | get, list, patch | - -Weave GitOps needs to be able to query the [CRDs](https://fluxcd.io/docs/components/) that Flux uses before it can accurately display Flux state. The -`get` and `list` permissions facilitate this. - -The `patch` permissions are used for two features: to suspend and resume -reconciliation of a resource by modifying the 'spec' of a resource, -and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that `flux suspend`, -`flux resume`, and `flux reconcile` does on the CLI. - -#### Resources Managed via Flux - -| API Group | Resources | Permissions | -|---------------------------|--------------------------------------------------------------------------------|------------------| -| "" | configmaps, secrets, pods, services, persistent volumes, persistent volume claims | get, list, watch | -| apps | deployments, replica sets, stateful sets | get, list, watch | -| batch | jobs, cron jobs | get, list, watch | -| autoscaling | horizontal pod autoscalers | get, list, watch | -| rbac.authorization.k8s.io | roles, cluster roles, rolebindings, cluster role bindings | get, list, watch | -| networking.k8s.io | ingresses | get, list, watch | - -Weave GitOps reads basic resources so that it can monitor the effect that Flux has -on what's running. - -Reading `secrets` enables Weave GitOps to monitor the state of Helm releases -as that's where it stores the [state by default](https://helm.sh/docs/faq/changes_since_helm2/#secrets-as-the-default-storage-driver). -For clarity this these are the Helm release objects _not_ the Flux HelmRelease -resource (which are dealt with by the earlier section). - -#### Feedback from Flux - -Flux communicates the status of itself primarily via events. -These events will show when reconciliations start and stop, whether they're successful, -and information as to why they're not. - - - -### Customise the UI - -#### Login - -The label of the OIDC button on the login screen is configurable via a feature flag environment variable. -This can give your users a more familiar experience when logging in. - -Adjust the configuration in the Helm `values.yaml` file or the `spec.values` section of the Weave GitOps `HelmRelease` resource: - -```yaml -extraEnvVars: - - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL - value: "Login with ACME" -``` - - - - - -## Next Steps - -Here are a couple of options for you to take your next steps with WGE. Explore one option or all of them, in no particular order. - -- [Cluster Management](https://docs.gitops.weave.works/docs/next/cluster-management/intro/): We'll show you how to join WGE to a cluster and install an application on that cluster *without* using Cluster API. But if you prefer using Cluster API, our docs cover that too. -- Install the [Terraform Controller](https://weaveworks.github.io/tf-controller/) to reconcile your Terraform resources in a GitOps way. With Flux and the TF Controller, WGE makes it easy to add Terraform templates to your clusters and continuously reconcile any changes made to the Terraform source manifest. -- Install [Policy agent](../../policy/intro.mdx), which comes packaged with the WGE chart. - -## Further Reference - -### CLI - -- `--kubeconfig` Paths to a kubeconfig. Only required if out-of-cluster. -- `--bootstrap-flux` chose whether you want to install flux in the generic way in case no flux installation detected -- `-b`, `--branch` git branch for your flux repository (example: main) -- `-i`, `--client-id` OIDC client ID -- `--client-secret` OIDC client secret -- `--components-extra` extra components to be installed from (policy-agent, tf-controller) -- `--discovery-url` OIDC discovery URL -- `--export` write to stdout the bootstrapping manifests without writing in the cluster or Git. It requires Flux to be bootstrapped. -- `--git-password` git password/token used in https authentication type -- `--git-username` git username used in https authentication type -- `-h`, `--help` help for bootstrap -- `-k`, `--private-key` private key path. This key will be used to push the Weave GitOps Enterprise's resources to the default cluster repository -- `-c`, `--private-key-password` private key password. If the private key is encrypted using password -- `-r`, `--repo-path` git path for your flux repository (example: clusters/my-cluster) -- `--repo-url` Git repo URL for your Flux repository. For supported URL examples see [here](https://fluxcd.io/flux/cmd/flux_bootstrap_git/) -- `-s`, `--silent` chose the defaults with current provided information without asking any questions -- `-v`, `--version` version of Weave GitOps Enterprise (should be from the latest 3 versions) -- `-p`, `--password` The Weave GitOps Enterprise password for dashboard access \ No newline at end of file diff --git a/website/docs/enterprise/getting-started/intro-enterprise.mdx b/website/docs/enterprise/getting-started/intro-enterprise.mdx index 6271d9bb6b..2effb4747e 100644 --- a/website/docs/enterprise/getting-started/intro-enterprise.mdx +++ b/website/docs/enterprise/getting-started/intro-enterprise.mdx @@ -27,9 +27,9 @@ We propose you to tackle it in three days: ### Day 1: Onboard the team -[**Onboard Platform Engineers**](../install-enterprise-onboard-platform-engineers): you want to harden your setup to onboard other Platform Engineers. Other Platform Engineers setup any WGE capabilities for your devs. +[**Onboard Platform Engineers**](../install-enterprise-onboard): you want to harden your setup to onboard other Platform Engineers. Other Platform Engineers setup any WGE capabilities for your devs. -[**Onboard Developers**](../install-enterprise-onboard-platform-engineers): the platform capabilities have been setup and you ready to start onboard developers. +[**Onboard Developers**](../install-enterprise-onboard): the platform capabilities have been setup and you ready to start onboard developers. ### Day 2: Operate & Improve diff --git a/website/sidebars.js b/website/sidebars.js index 006d150154..dc717d7746 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -50,7 +50,8 @@ module.exports = { "enterprise/getting-started/install-enterprise-getting-started-manual", ], }, - "enterprise/getting-started/install-enterprise-onboard-platform-engineers", + "enterprise/getting-started/install-enterprise-getting-started-onboard", + "enterprise/getting-started/install-enterprise-getting-started-expand", "enterprise/getting-started/releases-enterprise", { type: "category",