Skip to content

Commit

Permalink
Update enterprise getting started guide with Day 2
Browse files Browse the repository at this point in the history 
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 <[email protected]>
  • Loading branch information
@enekofb
enekofb committed Dec 27, 2023
1 parent e83a1d7 commit 5217600
Show file tree
Hide file tree
Showing 7 changed files with 763 additions and 786 deletions.
380 changes: 380 additions & 0 deletions ...e/docs/enterprise/getting-started/install-enterprise-getting-started-expand.mdx
View file
Original file line number Diff line number Diff line change
@@ -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.

<Tabs groupId="git-provider" default>
<TabItem value="github" label="GitHub">
GitHub requires no additional configuration for OAuth git access
</TabItem>
<TabItem value="gitlab" label="GitLab">

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"
```

</TabItem>
<TabItem value="bitbucket-server" label="BitBucket Server">

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.

<figure>

<img src={oauthBitbucket} width="500"/>

<figcaption>Configuring a new incoming application link</figcaption>
</figure>


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`

:::

</TabItem>

<TabItem value="azure-devops" label="Azure DevOps">

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.

<figure>
<img src={oauthAzureDevOps}/>
<figcaption>Creating a new application</figcaption>
</figure>

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.

<figure>
<img src={oauthAzureDevOpsSuccess}/>
<figcaption>Application settings</figcaption>
</figure>

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.

</TabItem>
</Tabs>

## 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:

<Tabs groupId="policy agent" default>
<TabItem value="cli" label="cli">

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)
</TabItem>
<TabItem value="manual" label="manual">

[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.

</TabItem>
</Tabs>

## 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"
```



2 changes: 1 addition & 1 deletion ...e/docs/enterprise/getting-started/install-enterprise-getting-started-manual.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
---

Expand Down
Loading

0 comments on commit 5217600

Please sign in to comment.