Skip to content

Commit 2f9eae5

Browse files
author
Charlie Egan
authored
docs: Add EvergreenCodeBlock for code with version (#7706)
This adds a new EvergreenCodeBlock component to the documentation site that allows code blocks to contain template for the current versions of opa components. This means we can show the current version in docs, but don't need update the version in every code block when we release a new version. Fixes #7705 In the future, it would be nice to pull the latest release for this on build since the envoy release sometimes lags behind the opa release a small amount, but for now this is a step in the right direction. The kube-mgmt version is also manually set, but at least this component owns all versioned code blocks in the documentation now. Signed-off-by: Charlie Egan <charlie@styra.com>
1 parent d2b2ba5 commit 2f9eae5

12 files changed

Lines changed: 95 additions & 23 deletions

‎docs/docs/deployments.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -174,9 +174,8 @@ Next, create a Deployment to run OPA. The ConfigMap containing the policy is
174174
volume mounted into the container. This allows OPA to load the policy from
175175
the file system.
176176

177-
**deployment-opa.yaml**:
178-
179-
```yaml
177+
<EvergreenCodeBlock>
178+
```yaml title="deployment-opa.yaml"
180179
apiVersion: apps/v1
181180
kind: Deployment
182181
metadata:
@@ -196,7 +195,7 @@ spec:
196195
spec:
197196
containers:
198197
- name: opa
199-
image: openpolicyagent/opa:{{< current_docker_version >}}
198+
image: openpolicyagent/opa:{{ current_version_docker }}
200199
ports:
201200
- name: http
202201
containerPort: 8181
@@ -214,6 +213,7 @@ spec:
214213
configMap:
215214
name: example-policy
216215
```
216+
</EvergreenCodeBlock>
217217
218218
```bash
219219
kubectl create -f deployment-opa.yaml
@@ -276,10 +276,11 @@ OPA exposes a `/health` API endpoint that you can configure Kubernetes
276276
[Readiness and Liveness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
277277
to call. For example:
278278

279+
<EvergreenCodeBlock>
279280
```yaml
280281
containers:
281282
- name: opa
282-
image: openpolicyagent/opa:{{< current_docker_version >}}
283+
image: openpolicyagent/opa:{{ current_version_docker }}
283284
ports:
284285
- name: http
285286
containerPort: 8181
@@ -307,6 +308,7 @@ containers:
307308
initialDelaySeconds: 5
308309
periodSeconds: 5
309310
```
311+
</EvergreenCodeBlock>
310312
311313
See the [Health API](./rest-api#health-api) documentation for more detail on the `/health` API endpoint.
312314

‎docs/docs/envoy/performance.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,9 +110,10 @@ layered_runtime:
110110
111111
Now let's deploy OPA as an External Authorization server. Below is a sample configuration for the OPA-Envoy container:
112112
113+
<EvergreenCodeBlock>
113114
```yaml
114115
containers:
115-
- image: openpolicyagent/opa:{{< current_opa_envoy_docker_version >}}
116+
- image: openpolicyagent/opa:{{ current_version_docker_envoy }}
116117
imagePullPolicy: IfNotPresent
117118
name: opa
118119
resources:
@@ -140,6 +141,7 @@ containers:
140141
path: /health?plugins
141142
port: 8282
142143
```
144+
</EvergreenCodeBlock>
143145
144146
> 💡 Consider specifying CPU and memory resource requests and limits for the OPA and other containers to prevent
145147
> deployments from resource starvation.

‎docs/docs/envoy/tutorial-gloo-edge.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,9 +178,10 @@ docker run --rm --name bundle-server -d -p 8888:80 -v ${PWD}:/usr/share/nginx/ht
178178

179179
### 6. Setup OPA-Envoy
180180

181-
Create a deployment as shown below and save it in **deployments.yaml**
181+
Create a deployment as shown below:
182182

183-
```yaml
183+
<EvergreenCodeBlock>
184+
```yaml title="deployments.yaml"
184185
apiVersion: apps/v1
185186
kind: Deployment
186187
metadata:
@@ -199,7 +200,7 @@ spec:
199200
spec:
200201
containers:
201202
- name: opa
202-
image: openpolicyagent/opa:{{< current_opa_envoy_docker_version >}}
203+
image: openpolicyagent/opa:{{ current_version_docker_envoy }}
203204
volumeMounts:
204205
- readOnly: true
205206
mountPath: /policy
@@ -218,6 +219,7 @@ spec:
218219
volumes:
219220
- name: opa-policy
220221
```
222+
</EvergreenCodeBlock>
221223
222224
```bash
223225
kubectl apply -f deployments.yaml

‎docs/docs/graphql-api-authorization.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,10 +158,11 @@ You should now see a policy bundle (`bundle.tar.gz`) in your working directory.
158158

159159
Next, create a `docker-compose.yaml` file that runs OPA, a bundle server and the demo GraphQL server.
160160

161+
<EvergreenCodeBlock>
161162
```yaml title="docker-compose.yaml"
162163
services:
163164
opa:
164-
image: openpolicyagent/opa:{{< current_docker_version >}}
165+
image: openpolicyagent/opa:{{ current_version_docker }}
165166
ports:
166167
- "8181:8181"
167168
command:
@@ -192,6 +193,7 @@ services:
192193
volumes:
193194
- ./bundles/:/usr/share/nginx/html/
194195
```
196+
</EvergreenCodeBlock>
195197
196198
Then run `docker-compose` to pull and run the containers.
197199

‎docs/docs/http-api-authorization.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,12 @@ You should now see a policy bundle (`bundle.tar.gz`) in your working directory (
7171

7272
Next, create a `docker-compose.yaml` file that runs OPA, a bundle server and the demo web server.
7373

74+
<EvergreenCodeBlock>
7475
```yaml title="docker-compose.yaml"
7576
version: "2"
7677
services:
7778
opa:
78-
image: openpolicyagent/opa:{{< current_docker_version >}}
79+
image: openpolicyagent/opa:{{ current_version_docker }}
7980
ports:
8081
- 8181:8181
8182
# WARNING: OPA is NOT running with an authorization policy configured. This
@@ -110,6 +111,7 @@ services:
110111
volumes:
111112
- ./bundles:/usr/share/nginx/html/bundles
112113
```
114+
</EvergreenCodeBlock>
113115
114116
Then run `docker-compose` to pull and run the containers.
115117

‎docs/docs/kafka-authorization.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,9 @@ For more information on how to configure the OPA plugin for Kafka, see the plugi
7070

7171
Next, create a `docker-compose.yaml` file that runs OPA, Nginx, ZooKeeper, and Kafka.
7272

73-
**docker-compose.yaml**:
73+
<EvergreenCodeBlock>
7474

75-
```yaml
75+
```yaml title="docker-compose.yaml"
7676
services:
7777
nginx:
7878
image: nginx:1.21.4
@@ -81,7 +81,7 @@ services:
8181
ports:
8282
- "80:80"
8383
opa:
84-
image: openpolicyagent/opa:{{< current_docker_version >}}
84+
image: openpolicyagent/opa:{{ current_version_docker }}
8585
ports:
8686
- "8181:8181"
8787
command:
@@ -133,6 +133,8 @@ services:
133133
- zookeeper
134134
```
135135
136+
</EvergreenCodeBlock>
137+
136138
#### Authentication
137139
138140
The Docker Compose file defined above requires **SSL client authentication**

‎docs/docs/kubernetes/tutorial.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,8 @@ docker run --rm --name bundle-server -d -p 8888:80 -v ${PWD}:/usr/share/nginx/ht
247247

248248
Next, use the file below to deploy OPA as an admission controller.
249249

250-
```yaml title="admission-controller.yaml"
250+
<EvergreenCodeBlock>
251+
```
251252
# Grant OPA/kube-mgmt read-only access to resources. This lets kube-mgmt
252253
# replicate resources into OPA so they can be used in policies.
253254
kind: ClusterRoleBinding
@@ -328,7 +329,7 @@ spec:
328329
# authentication and authorization on the daemon. See the Security page for
329330
# details: https://www.openpolicyagent.org/docs/security.html.
330331
- name: opa
331-
image: openpolicyagent/opa:{{< current_docker_version >}}
332+
image: openpolicyagent/opa:{{ current_version_docker }}
332333
args:
333334
- "run"
334335
- "--server"
@@ -360,7 +361,7 @@ spec:
360361
initialDelaySeconds: 3
361362
periodSeconds: 5
362363
- name: kube-mgmt
363-
image: openpolicyagent/kube-mgmt:2.0.1
364+
image: openpolicyagent/kube-mgmt:{{ current_version_kube_mgmt }}
364365
args:
365366
- "--replicate-cluster=v1/namespaces"
366367
- "--replicate=networking.k8s.io/v1/ingresses"
@@ -369,6 +370,7 @@ spec:
369370
secret:
370371
secretName: opa-server
371372
```
373+
</EvergreenCodeBlock>
372374

373375
> ⚠️ If using `kind` to run a local Kubernetes cluster, the bundle service URL should be `http://host.docker.internal:8888`.
374376

‎docs/docs/management-decision-logs.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,14 @@ updates will be sent to `/logs`.
3030
The message body contains a gzip compressed JSON array. Each array element (event)
3131
represents a policy decision returned by OPA.
3232

33+
<EvergreenCodeBlock>
3334
```json
3435
[
3536
{
3637
"labels": {
3738
"app": "my-example-app",
3839
"id": "1780d507-aea2-45cc-ae50-fa153c8e4a5a",
39-
"version": "{{< current_version >}}"
40+
"version": "{{ current_version }}"
4041
},
4142
"decision_id": "4ca636c1-55e4-417a-b1d8-4aceb67960d1",
4243
"bundles": {
@@ -55,6 +56,7 @@ represents a policy decision returned by OPA.
5556
}
5657
]
5758
```
59+
</EvergreenCodeBlock>
5860

5961
Decision log updates contain the following fields:
6062

‎docs/docs/management-status.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,13 @@ The partition name is an optional path segment that can be used to route
3434
status updates to different backends. If the partition name is not configured
3535
on the agent, updates will be sent to `/status`.
3636

37+
<EvergreenCodeBlock>
3738
```json
3839
{
3940
"labels": {
4041
"app": "my-example-app",
4142
"id": "1780d507-aea2-45cc-ae50-fa153c8e4a5a",
42-
"version": "{{< current_version >}}"
43+
"version": "{{ current_version }}"
4344
},
4445
"bundles": {
4546
"http/example/authz": {
@@ -225,6 +226,7 @@ on the agent, updates will be sent to `/status`.
225226
}
226227
}
227228
```
229+
</EvergreenCodeBlock>
228230

229231
Status updates contain the following fields:
230232

‎docs/docs/ssh-and-sudo-authorization.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,12 @@ with OPA. The dummy SSH hosts are just containers running sshd inside.
4646
First, create a `tutorial-docker-compose.yaml` file that runs OPA and the containers that
4747
represent our backend and frontend hosts.
4848

49-
**tutorial-docker-compose.yaml**:
50-
51-
```yaml
49+
<EvergreenCodeBlock>
50+
```yaml title="tutorial-docker-compose.yaml"
5251
version: "2"
5352
services:
5453
opa:
55-
image: openpolicyagent/opa:{{< current_docker_version >}}
54+
image: openpolicyagent/opa:{{ current_version_docker }}
5655
ports:
5756
- "8181:8181"
5857
# WARNING: OPA is NOT running with an authorization policy configured. This
@@ -88,6 +87,7 @@ services:
8887
volumes:
8988
- ./bundles:/usr/share/nginx/html/bundles
9089
```
90+
</EvergreenCodeBlock>
9191
9292
The `tutorial-docker-compose.yaml` file requires two other local files:
9393
`frontend_host_id.json` and `backend_host_id.json`. These files are mounted

0 commit comments

Comments
 (0)