Skip to content

Commit ad51501

Browse files
pantierrapantierra
committed
Extended kubernetes auth documentation.
1 parent bf53b81 commit ad51501

File tree

3 files changed

+64
-60
lines changed

3 files changed

+64
-60
lines changed

‎docs/user-guide/deployment.md‎

Lines changed: 1 addition & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -61,47 +61,4 @@ docker pull ghcr.io/developmentseed/stac-auth-proxy:v0.7.1
6161
6262
## Kubernetes
6363
64-
The STAC Auth Proxy can be deployed to Kubernetes via the [Helm Chart available on the GitHub Container Registry (GHCR)](https://github.com/developmentseed/stac-auth-proxy/pkgs/container/stac-auth-proxy%2Fcharts%2Fstac-auth-proxy).
65-
66-
### Prerequisites
67-
68-
- Kubernetes 1.19+
69-
- Helm 3.2.0+
70-
71-
### Installation
72-
73-
```bash
74-
# Add the Helm repository
75-
helm registry login ghcr.io
76-
77-
# Install with minimal configuration
78-
helm install stac-auth-proxy oci://ghcr.io/developmentseed/stac-auth-proxy/charts/stac-auth-proxy \
79-
--set env.UPSTREAM_URL=https://your-stac-api.com/stac \
80-
--set env.OIDC_DISCOVERY_URL=https://your-auth-server/.well-known/openid-configuration \
81-
--set ingress.host=stac-proxy.your-domain.com
82-
```
83-
84-
### Configuration
85-
86-
| Parameter | Description | Required | Default |
87-
| ------------------------ | --------------------------------------------- | -------- | ------- |
88-
| `env.UPSTREAM_URL` | URL of the STAC API to proxy | Yes | - |
89-
| `env.OIDC_DISCOVERY_URL` | OpenID Connect discovery document URL | Yes | - |
90-
| `env` | Environment variables passed to the container | No | `{}` |
91-
| `ingress.enabled` | Enable ingress | No | `true` |
92-
| `ingress.className` | Ingress class name | No | `nginx` |
93-
| `ingress.host` | Hostname for the ingress | No | `""` |
94-
| `ingress.tls.enabled` | Enable TLS for ingress | No | `true` |
95-
| `replicaCount` | Number of replicas | No | `1` |
96-
97-
For a complete list of values, see the [values.yaml](https://github.com/developmentseed/stac-auth-proxy/blob/main/helm/values.yaml) file.
98-
99-
### Management
100-
101-
```bash
102-
# Upgrade
103-
helm upgrade stac-auth-proxy oci://ghcr.io/developmentseed/stac-auth-proxy/charts/stac-auth-proxy
104-
105-
# Uninstall
106-
helm uninstall stac-auth-proxy
107-
```
64+
See [Kubernetes deployment](kubernetes.md) for detailed instructions on deploying to Kubernetes using Helm.

helm/AUTHORIZATION.md renamed to docs/user-guide/kubernetes.md

Lines changed: 62 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,50 @@
1-
# Authorization configuration guide
1+
# Kubernetes Deployment
2+
3+
Deploy STAC Auth Proxy to Kubernetes using the Helm chart.
4+
5+
## Prerequisites
6+
7+
- Kubernetes 1.19+
8+
- Helm 3.2.0+
9+
10+
## Installation
11+
12+
```bash
13+
helm registry login ghcr.io
14+
15+
helm install stac-auth-proxy oci://ghcr.io/developmentseed/stac-auth-proxy/charts/stac-auth-proxy \
16+
--set env.UPSTREAM_URL=https://your-stac-api.com/stac \
17+
--set env.OIDC_DISCOVERY_URL=https://your-auth-server/.well-known/openid-configuration \
18+
--set ingress.host=stac-proxy.your-domain.com
19+
```
20+
21+
### Configuration
22+
23+
| Parameter | Description | Required | Default |
24+
| ------------------------ | --------------------------------------------- | -------- | ------- |
25+
| `env.UPSTREAM_URL` | URL of the STAC API to proxy | Yes | - |
26+
| `env.OIDC_DISCOVERY_URL` | OpenID Connect discovery document URL | Yes | - |
27+
| `env` | Environment variables passed to the container | No | `{}` |
28+
| `ingress.enabled` | Enable ingress | No | `true` |
29+
| `ingress.className` | Ingress class name | No | `nginx` |
30+
| `ingress.host` | Hostname for the ingress | No | `""` |
31+
| `ingress.tls.enabled` | Enable TLS for ingress | No | `true` |
32+
| `replicaCount` | Number of replicas | No | `1` |
33+
34+
For a complete list of values, see the [values.yaml](https://github.com/developmentseed/stac-auth-proxy/blob/main/helm/values.yaml) file.
35+
36+
## Authorization
237

338
The chart provides two levels of authorization:
439

5-
1. **[Route-level authorization](https://developmentseed.org/stac-auth-proxy/user-guide/route-level-auth/)**: Controls which API endpoints are accessible and by whom
6-
2. **[Record-level authorization](https://developmentseed.org/stac-auth-proxy/user-guide/record-level-auth/)**: Filters collections and items based on user permissions
40+
1. **[Route-level authorization](route-level-auth.md)**: Controls which API endpoints are accessible and by whom
41+
2. **[Record-level authorization](record-level-auth.md)**: Filters collections and items based on user permissions
742

8-
## Route-Level Authorization
43+
### Route-Level Authorization
944

1045
Configure via `authorization.route` section in `values.yaml`.
1146

12-
### Mode: `default` (Recommended)
47+
#### Mode: `default` (Recommended)
1348

1449
Public catalog with protected write operations. This is the most common configuration.
1550

@@ -21,7 +56,7 @@ authorization:
2156
2257
This automatically sets `DEFAULT_PUBLIC=true`, making all read endpoints public while requiring authentication for write operations.
2358

24-
### Mode: `custom`
59+
#### Mode: `custom`
2560

2661
Define specific public and private endpoints with custom rules.
2762

@@ -45,7 +80,7 @@ authorization:
4580
- `privateEndpoints`: Maps regex paths to HTTP methods or `[method, scope]` tuples
4681
- Scopes define required OAuth2 scopes for the operation
4782

48-
### Mode: `disabled`
83+
#### Mode: `disabled`
4984

5085
No route-level authorization applied.
5186

@@ -55,11 +90,11 @@ authorization:
5590
mode: "disabled"
5691
```
5792

58-
## Record-Level Authorization
93+
### Record-Level Authorization
5994

6095
Configure via `authorization.record` section in `values.yaml`.
6196

62-
### Mode: `disabled` (Default)
97+
#### Mode: `disabled` (Default)
6398

6499
No record-level filtering applied. All collections and items are visible to authenticated users.
65100

@@ -69,7 +104,7 @@ authorization:
69104
mode: "disabled"
70105
```
71106

72-
### Mode: `custom`
107+
#### Mode: `custom`
73108

74109
Use Python filter classes to control visibility of collections and items.
75110

@@ -87,9 +122,9 @@ This automatically:
87122
- Sets `COLLECTIONS_FILTER_CLS=stac_auth_proxy.custom_filters:CollectionsFilter`
88123
- Sets `ITEMS_FILTER_CLS=stac_auth_proxy.custom_filters:ItemsFilter`
89124

90-
Review the stac-auth-proxy [documentation for more information on custom filters](https://developmentseed.org/stac-auth-proxy/user-guide/record-level-auth/#custom-filter-factories).
125+
Review the stac-auth-proxy [documentation for more information on custom filters](record-level-auth.md#custom-filter-factories).
91126

92-
### Mode: `opa`
127+
#### Mode: `opa`
93128

94129
Use Open Policy Agent for policy-based filtering.
95130

@@ -106,9 +141,9 @@ This sets:
106141
- `ITEMS_FILTER_CLS=stac_auth_proxy.filters.opa:Opa`
107142
- `ITEMS_FILTER_ARGS='["http://opa-service:8181", "stac/items/allow"]'`
108143

109-
## Some configuration examples
144+
### Configuration Examples
110145

111-
### Example 1: Default for public catalog, protected writes
146+
#### Example 1: Default for public catalog, protected writes
112147

113148
```yaml
114149
authorization:
@@ -118,7 +153,7 @@ authorization:
118153
mode: "disabled"
119154
```
120155

121-
### Example 2: Fully protected catalog
156+
#### Example 2: Fully protected catalog
122157

123158
```yaml
124159
authorization:
@@ -135,7 +170,7 @@ authorization:
135170
filtersFile: "data/custom_filters.py"
136171
```
137172

138-
## Direct configuration
173+
### Direct Configuration
139174

140175
Existing charts using `env` variables directly continue to work:
141176

@@ -148,3 +183,14 @@ env:
148183
```
149184

150185
**Environment variables specified in `env` take precedence over `authorization` settings.**
186+
187+
## Management
188+
189+
```bash
190+
# Upgrade
191+
helm upgrade stac-auth-proxy oci://ghcr.io/developmentseed/stac-auth-proxy/charts/stac-auth-proxy
192+
193+
# Uninstall
194+
helm uninstall stac-auth-proxy
195+
```
196+

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ nav:
3535
- Route-Level Auth: user-guide/route-level-auth.md
3636
- Record-Level Auth: user-guide/record-level-auth.md
3737
- Deployment: user-guide/deployment.md
38+
- Kubernetes: user-guide/kubernetes.md
3839
- Tips: user-guide/tips.md
3940
- Architecture:
4041
- Middleware Stack: architecture/middleware-stack.md

0 commit comments

Comments
 (0)