Skip to content

Commit a4ba6b1

Browse files
enekofbenekofb
committed
Add advanced topics section to enterprise documentation
Introduced a new 'Advanced Topics' page in the enterprise documentation. This page covers detailed information on OIDC customization, scopes, claims, Cluster User, User Permissions and how to customize the UI for users. It also improves the organization of our 'Getting Started' guide by breaking it down into step-by-step sections. This helps provide a clearer and better-structured journey for users. Signed-off-by: Eneko Fernandez <[email protected]>
1 parent 175b9da commit a4ba6b1

File tree

2 files changed

+215
-1
lines changed

2 files changed

+215
-1
lines changed

‎website/docs/enterprise/getting-started/install-enterprise-getting-started-advanced-topics.mdx

+204
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
title: Advanced Topics
3+
hide_title: true
4+
toc_max_heading_level: 4
5+
pagination_prev: enterprise/getting-started/install-enterprise-getting-started-onboard
6+
pagination_next: enterprise/getting-started/install-enterprise-getting-started-expand
7+
8+
---
9+
10+
import Tabs from "@theme/Tabs";
11+
import TabItem from "@theme/TabItem";
12+
import TierLabel from "@site/docs/_components/TierLabel";
13+
import AlphaWarning from "../../_components/_alpha_warning.mdx";
14+
import CurlCodeBlock from "../../_components/CurlCodeBlock";
15+
import oauthBitbucket from '/img/oauth-bitbucket.png';
16+
import oauthAzureDevOps from '/img/oauth-azure-devops.png';
17+
import oauthAzureDevOpsSuccess from '/img/oauth-azure-devops-success.png';
18+
19+
# Advanced Topics
20+
21+
## OIDC
22+
23+
### Customization
24+
25+
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).
26+
27+
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.
28+
29+
### Scopes
30+
31+
By default, the following scopes are requested: "openid","offline_access","email","groups".
32+
33+
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.
34+
35+
"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.
36+
```sh
37+
kubectl create secret generic oidc-auth \
38+
--namespace flux-system \
39+
--from-literal=issuerURL=$oidc-issuer-url \
40+
--from-literal=clientID=$client-id \
41+
--from-literal=clientSecret=$client-secret \
42+
--from-literal=redirectURL=redirect-url \
43+
--from-literal=tokenDuration=token-duration \
44+
--from-literal=customScopes=custom,scopes
45+
```
46+
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.
47+
48+
### Claims
49+
50+
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.
51+
52+
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`.
53+
54+
Again, you can configure these from the `oidc-auth` `Secret`.
55+
56+
```sh
57+
kubectl create secret generic oidc-auth \
58+
--namespace flux-system \
59+
--from-literal=issuerURL=oidc-issuer-url \
60+
--from-literal=clientID=client-id \
61+
--from-literal=clientSecret=client-secret \
62+
--from-literal=redirectURL=redirect-url \
63+
--from-literal=tokenDuration=token-duration \
64+
--from-literal=claimUsername=sub \
65+
--from-literal=claimGroups=groups
66+
```
67+
There are two separate configuration keys. You can override them separately. They should match your `kube-apiserver` configuration.
68+
69+
## Cluster User
70+
71+
### Update Username or Password
72+
73+
To change either the username or the password, recreate the `cluster-user-auth`
74+
with the new details.
75+
76+
Only one Cluster User can be created this way. To add more users, enable an OIDC provider.
77+
78+
### Update Permissions
79+
80+
If required, the permissions can be expanded with the `rbac.additionalRules` field in the
81+
[Helm Chart](../../references/helm-reference.md).
82+
83+
Follow the instructions in the next section in order to configure RBAC correctly.
84+
85+
### Remove It
86+
87+
To remove the Cluster User as a login method, set the following values in the
88+
[Helm Chart](../../references/helm-reference.md):
89+
90+
```yaml
91+
#
92+
adminUser:
93+
create: false
94+
#
95+
additionalArgs:
96+
- --auth-methods=oidc
97+
#
98+
```
99+
:::caution If you are disabling an already existing Cluster User
100+
101+
If you are disabling an already existing Cluster User, you will need to
102+
manually delete the Kubernetes Secret and any User Roles that were created on
103+
the cluster.
104+
105+
:::
106+
107+
## User Permissions
108+
109+
This section discusses the [Kubernetes permissions](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
110+
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
111+
Flux stores its resources by default—with the following permissions:
112+
113+
```yaml
114+
rules:
115+
# Flux Resources
116+
- apiGroups: ["source.toolkit.fluxcd.io"]
117+
resources: [ "buckets", "helmcharts", "gitrepositories", "helmrepositories", "ocirepositories" ]
118+
verbs: [ "get", "list", "watch", "patch" ]
119+
120+
- apiGroups: ["kustomize.toolkit.fluxcd.io"]
121+
resources: [ "kustomizations" ]
122+
verbs: [ "get", "list", "watch", "patch" ]
123+
124+
- apiGroups: ["helm.toolkit.fluxcd.io"]
125+
resources: [ "helmreleases" ]
126+
verbs: [ "get", "list", "watch", "patch" ]
127+
128+
- apiGroups: [ "notification.toolkit.fluxcd.io" ]
129+
resources: [ "providers", "alerts" ]
130+
verbs: [ "get", "list", "watch", "patch" ]
131+
132+
- apiGroups: ["infra.contrib.fluxcd.io"]
133+
resources: ["terraforms"]
134+
verbs: [ "get", "list", "watch", "patch" ]
135+
136+
# Read access for all other Kubernetes objects
137+
- apiGroups: ["*"]
138+
resources: ["*"]
139+
verbs: [ "get", "list", "watch" ]
140+
```
141+
142+
For a wider scope, the User can be bound to a ClusterRole with the same set.
143+
144+
On top of this you can add other permissions to view WGE resources like `GitOpsSets` and `Templates`.
145+
146+
### Flux Resources
147+
148+
The following table lists resources that Flux works with directly.
149+
150+
| API Group | Resources | Permissions |
151+
| ------------------------------ | ----------------------------------------------------------------------- | ---------------- |
152+
| kustomize.toolkit.fluxcd.io | kustomizations | get, list, patch |
153+
| helm.toolkit.fluxcd.io | Helm Releases | get, list, patch |
154+
| source.toolkit.fluxcd.io | buckets, Helm charts, Git repositories, Helm repositories, OCI repositories | get, list, patch |
155+
| notification.toolkit.fluxcd.io | providers, alerts | get, list |
156+
| infra.contrib.fluxcd.io | [Terraform](https://github.com/weaveworks/tf-controller) | get, list, patch |
157+
158+
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
159+
`get` and `list` permissions facilitate this.
160+
161+
The `patch` permissions are used for two features: to suspend and resume
162+
reconciliation of a resource by modifying the 'spec' of a resource,
163+
and to force reconciliation of a resource by modifying resource annotations. These features work in the same way that `flux suspend`,
164+
`flux resume`, and `flux reconcile` does on the CLI.
165+
166+
### Resources Managed via Flux
167+
168+
| API Group | Resources | Permissions |
169+
|---------------------------|--------------------------------------------------------------------------------|------------------|
170+
| "" | configmaps, secrets, pods, services, persistent volumes, persistent volume claims | get, list, watch |
171+
| apps | deployments, replica sets, stateful sets | get, list, watch |
172+
| batch | jobs, cron jobs | get, list, watch |
173+
| autoscaling | horizontal pod autoscalers | get, list, watch |
174+
| rbac.authorization.k8s.io | roles, cluster roles, rolebindings, cluster role bindings | get, list, watch |
175+
| networking.k8s.io | ingresses | get, list, watch |
176+
177+
Weave GitOps reads basic resources so that it can monitor the effect that Flux has
178+
on what's running.
179+
180+
Reading `secrets` enables Weave GitOps to monitor the state of Helm releases
181+
as that's where it stores the [state by default](https://helm.sh/docs/faq/changes_since_helm2/#secrets-as-the-default-storage-driver).
182+
For clarity this these are the Helm release objects _not_ the Flux HelmRelease
183+
resource (which are dealt with by the earlier section).
184+
185+
### Feedback from Flux
186+
187+
Flux communicates the status of itself primarily via events.
188+
These events will show when reconciliations start and stop, whether they're successful,
189+
and information as to why they're not.
190+
191+
## Customise the UI
192+
193+
### Login
194+
195+
The label of the OIDC button on the login screen is configurable via a feature flag environment variable.
196+
This can give your users a more familiar experience when logging in.
197+
198+
Adjust the configuration in the Helm `values.yaml` file or the `spec.values` section of the Weave GitOps `HelmRelease` resource:
199+
200+
```yaml
201+
extraEnvVars:
202+
- name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL
203+
value: "Login with ACME"
204+
```

‎website/sidebars.js

+11-1
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,17 @@ module.exports = {
5050
"enterprise/getting-started/install-enterprise-getting-started-manual",
5151
],
5252
},
53-
"enterprise/getting-started/install-enterprise-getting-started-onboard",
53+
{
54+
type: "category",
55+
label: "Step 2 - Complete and Onboard",
56+
link: {
57+
type: "doc",
58+
id: "enterprise/getting-started/install-enterprise-getting-started-onboard",
59+
},
60+
items: [
61+
"enterprise/getting-started/install-enterprise-getting-started-advanced-topics",
62+
],
63+
},
5464
"enterprise/getting-started/install-enterprise-getting-started-expand",
5565
"enterprise/getting-started/releases-enterprise",
5666
{

0 commit comments

Comments
 (0)