Skip to content

Commit 9bc6dde

Browse files
FilipBlongmuirnrfox
authored
OSSM-8269: OSSM documentation for sidecar injection (openshift-service-mesh#152)
* OSSM-8269: OSSM documentation for sidecar injection * Add more info on how revision name is derived * Adding a note about revision tag feature * Removing note about future feature as it's not allowed * Update docs/ossm/injection/README.md Co-authored-by: Nick Fox <[email protected]> * Review changes --------- Co-authored-by: Jamie Longmuir <[email protected]> Co-authored-by: Nick Fox <[email protected]>
1 parent 7f543e1 commit 9bc6dde

File tree

1 file changed

+129
-0
lines changed

1 file changed

+129
-0
lines changed

‎docs/ossm/injection/README.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
## Installing the Sidecar
2+
### Injection
3+
To include workloads as part of the service mesh and to begin using Istio's many features, pods must be injected with a sidecar proxy that will be configured by an Istio control plane.
4+
5+
Sidecar injection can be enabled via labels at the namespace or pod level. That also serves to identify the control plane managing the sidecar proxy(ies). By adding a valid injection label on a `Deployment`, pods created through that deployment will automatically have a sidecar added to them. By adding a valid pod injection label on a namespace, any new pods that are created in that namespace will automatically have a sidecar added to them.
6+
7+
The proxy configuration is injected at pod creation time using an [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/). As sidecar injection occurs at the pod-level, you won’t see any change to `Deployment` resources. Instead, you’ll want to check individual pods (via `oc describe`) to see the injected Istio proxy container.
8+
9+
### Identifying the revision name
10+
11+
The correct label used to enable sidecar injection depends on the control plane instance being used. A control plane instance is called a "revision" and is managed by the `IstioRevision` resource. The `Istio` control plane resource creates and manages `IstioRevision` resources, thus users do not typically have to create or modify them.
12+
13+
When the `Istio` resources's `spec.updateStrategy.type` is set to `InPlace`, the `IstioRevision` will have the same name as the `Istio` resource. When the `Istio` resources's `spec.updateStrategy.type` is set to `RevisionBased`, the `IstioRevision` will have the format `<Istio resource name>-v<version>`.
14+
15+
In most cases, there will be a single `IstioRevision` resource per `Istio` resource. During a revision based upgrade, there may be multiple `IstioRevision` instances present, each representing an independent control plane.
16+
17+
The available revision names can be checked with the command:
18+
19+
```console
20+
$ oc get istiorevision
21+
NAME READY STATUS IN USE VERSION AGE
22+
my-mesh-v1-23-0 True Healthy False v1.23.0 114s
23+
```
24+
25+
### Enabling sidecar injection - "default" revision
26+
27+
When the service mesh's `IstioRevision` name is "default", it's possible to use following labels on a namespace or a pod to enable sidecar injection:
28+
| Resource | Label | Enabled value | Disabled value |
29+
| --- | --- | --- | --- |
30+
| Namespace | `istio-injection` | `enabled` | `disabled` |
31+
| Pod | `sidecar.istio.io/inject` | `"true"` | `"false"` |
32+
33+
### Enabling sidecar injection - other revisions
34+
35+
When the `IstioRevision` name is not "default", then the specific `IstioRevision` name must be used with the `istio.io/rev` label to map the pod to the desired control plane while enabling sidecar injection.
36+
37+
For example, with the revision shown above, the following labels would enable sidecar injection:
38+
| Resource | Enabled Label | Disabled Label |
39+
| --- | --- | --- |
40+
| Namespace | `istio.io/rev=my-mesh-v1-23-0` | `istio-injection=disabled` |
41+
| Pod | `istio.io/rev=my-mesh-v1-23-0` | `sidecar.istio.io/inject="false"` |
42+
43+
### Sidecar injection logic
44+
45+
If the `istio-injection` label and the `istio.io/rev` label are both present on the same namespace, the `istio-injection` label (mapping to the "default" revision) will take precedence.
46+
47+
The injector is configured with the following logic:
48+
49+
1. If either label (`istio-injection` or `sidecar.istio.io/inject`) is disabled, the pod is not injected.
50+
2. If either label (`istio-injection` or `sidecar.istio.io/inject` or `istio.io/rev`) is enabled, the pod is injected.
51+
52+
### Example: Enabling sidecar injection
53+
Prerequisites:
54+
- The OpenShift Service Mesh operator has been installed
55+
- An Istio CNI resource has been created
56+
57+
1. Create the `istio-system` namespace:
58+
```bash
59+
oc create ns istio-system
60+
```
61+
1. Prepare `default` `istio.yaml`:
62+
```yaml
63+
kind: Istio
64+
apiVersion: sailoperator.io/v1alpha1
65+
metadata:
66+
name: default
67+
spec:
68+
namespace: istio-system
69+
updateStrategy:
70+
type: InPlace
71+
version: v1.23.0
72+
```
73+
1. Create the `default` Istio CR in `istio-system` namespace:
74+
```bash
75+
oc apply -f istio.yaml
76+
```
77+
1. Wait for `Istio` to become ready.
78+
```bash
79+
oc wait --for=condition=Ready istios/default -n istio-system
80+
```
81+
1. Deploy the `sleep` app:
82+
```bash
83+
oc apply -f https://raw.githubusercontent.com/istio/istio/release-1.23/samples/sleep/sleep.yaml
84+
```
85+
1. Verify both the deployment and pod have a single container:
86+
```bash
87+
oc get deployment -o wide
88+
NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
89+
sleep 1/1 1 1 16s sleep curlimages/curl app=sleep
90+
oc get pod -l app=sleep
91+
NAME READY STATUS RESTARTS AGE
92+
sleep-5577c64d7c-ntn9d 1/1 Running 0 16s
93+
```
94+
1. Label the `default` namespace with `istio-injection=enabled`:
95+
```bash
96+
oc label namespace default istio-injection=enabled
97+
```
98+
1. Injection occurs at pod creation time. Remove the running pod to be injected with a proxy sidecar.
99+
```bash
100+
oc delete pod -l app=sleep
101+
```
102+
1. Verify a new pod is created with the injected sidecar. The original pod has `1/1 READY` containers, and the pod with injected sidecar has `2/2 READY` containers.
103+
```bash
104+
oc get pod -l app=sleep
105+
NAME READY STATUS RESTARTS AGE
106+
sleep-5577c64d7c-w9vpk 2/2 Running 0 12s
107+
```
108+
1. View the detailed state of the injected pod. You should see the injected `istio-proxy` container.
109+
```bash
110+
oc describe pod -l app=sleep
111+
...
112+
Events:
113+
Type Reason Age From Message
114+
---- ------ ---- ---- -------
115+
Normal Scheduled 50s default-scheduler Successfully assigned default/sleep-5577c64d7c-w9vpk to user-rhos-d-1-v8rnx-worker-0-rwjrr
116+
Normal AddedInterface 50s multus Add eth0 [10.128.2.179/23] from ovn-kubernetes
117+
Normal Pulled 50s kubelet Container image "registry.redhat.io/openshift-service-mesh-tech-preview/istio-proxyv2-rhel9@sha256:c0170ef9a34869828a5f2fea285a7cda543d99e268f7771e6433c54d6b2cbaf4" already present on machine
118+
Normal Created 50s kubelet Created container istio-validation
119+
Normal Started 50s kubelet Started container istio-validation
120+
Normal Pulled 50s kubelet Container image "curlimages/curl" already present on machine
121+
Normal Created 50s kubelet Created container sleep
122+
Normal Started 50s kubelet Started container sleep
123+
Normal Pulled 50s kubelet Container image "registry.redhat.io/openshift-service-mesh-tech-preview/istio-proxyv2-rhel9@sha256:c0170ef9a34869828a5f2fea285a7cda543d99e268f7771e6433c54d6b2cbaf4" already present on machine
124+
Normal Created 50s kubelet Created container istio-proxy
125+
Normal Started 50s kubelet Started container istio-proxy
126+
...
127+
```
128+
> [!CAUTION]
129+
> Injection using the `istioctl kube-inject` which is not supported by Red Hat OpenShift Service Mesh.

0 commit comments

Comments
 (0)