diff --git a/.github/styles/config/vocabularies/CalicoDocs/accept.txt b/.github/styles/config/vocabularies/CalicoDocs/accept.txt index 8ea8acb9c9..e814ebcf71 100644 --- a/.github/styles/config/vocabularies/CalicoDocs/accept.txt +++ b/.github/styles/config/vocabularies/CalicoDocs/accept.txt @@ -49,3 +49,4 @@ calicoq Goldmane Tigera Operator Maglev +Dikastes diff --git a/calico/network-policy/istio/app-layer-policy.mdx b/calico/network-policy/istio/app-layer-policy.mdx index e9c3751677..9c3d6c5712 100644 --- a/calico/network-policy/istio/app-layer-policy.mdx +++ b/calico/network-policy/istio/app-layer-policy.mdx @@ -4,122 +4,329 @@ description: Enforce network policy for Istio service mesh including matching on import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Enforce network policy for Istio +# Enforce Calico network policy for Istio service mesh -## Big picture +## Overview -$[prodname] integrates seamlessly with Istio to enforce network policy within the Istio service mesh. +You can enforce $[prodname] network policy for Istio application layer policy using the Dikastes sidecar. Dikastes enables $[prodname] to integrate with Istio's Envoy proxy to enforce fine-grained Layer 7 (HTTP) policies. -## Value +### Value -$[prodname] network policy for Istio lets you enforce application layer attributes like HTTP methods or paths, and cryptographically secure identities for Istio-enabled apps. +- **Pod traffic controls for Istio-enabled apps**: Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Security alignment with zero trust**: Supports zero-trust network models through traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +- **Familiar policy language**: Apply Kubernetes network policies and $[prodname] network policies that you already know. -## Concepts +## Before you begin -### Benefits of the Istio integration +**Required** -The $[prodname] support for Istio service mesh has the following benefits: +- $[prodname] CNI is installed and configured +- `kubectl` and `istioctl` CLI tools are installed +- MutatingAdmissionWebhook admission controller is enabled -- **Pod traffic controls** +**Supported Istio versions** - Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Istio v1.28.1** (recommended) +- **Istio v1.22+** (minimum required for Kubernetes native sidecar support) -- **Supports security goals** +:::note - Enables adoption of a zero trust network model for security, including traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +This guide requires Istio 1.22+ with Kubernetes native sidecars. Traditional sidecar injection is not supported. For legacy Istio versions (v1.15.2, v1.10.2), see [Legacy Installation](#legacy-installation-configmap-patching). -- **Familiar policy language** +::: - Kubernetes network policies and $[prodname] network policies work as is; users do not need to learn another network policy model to adopt Istio. +**Required Kubernetes versions** -See [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) to learn how application layer policy provides second-factor authentication for the mythical Yao Bank. +- **Kubernetes v1.29+**: Required for native sidecar support -## Before you begin +## How to -**Required** +This guide covers the usage of [IstioOperator](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) -- [$[prodname] is installed](../../getting-started/index.mdx) -- [calicoctl is installed and configured](../../operations/calicoctl/install.mdx) -- [MutatingAdmissionWebhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) enabled +For the ConfigMap patching method, see [Legacy Installation](#legacy-installation-configmap-patching). -**Istio support** +### 1. Enable application layer policy -Following Istio versions have been verified to work with application layer policies: +Enable the Policy Sync API in Felix to allow Dikastes to query policy decisions. -- Istio v1.15.2 -- Istio v1.10.2 + + -Istio v1.9.x and lower are **not** supported. +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"policySyncPathPrefix":"/var/run/nodeagent"}}' +``` -Although we expect future minor versions to work with the corresponding manifest below (for example, v1.10.2 or v1.15.2), manifest compatibility depends entirely on the upstream changes in the respective Istio release. + + -## How to +```bash +calicoctl patch FelixConfiguration default --patch \ + '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +``` -1. [Enable application layer policy](#enable-application-layer-policy) -2. [Install Calico CSI Driver](#install-calico-csi-driver) -3. [Install Istio](#install-istio) -4. [Update Istio sidecar injector](#update-istio-sidecar-injector) -5. [Add Calico authorization services to the mesh](#add-calico-authorization-services-to-the-mesh) -6. [Add namespace labels](#add-namespace-labels) + + -### Enable application layer policy +**Optional**: If using the $[prodname] operator, disable deprecated Flex Volumes: -To enable the application layer policy, you must enable the **Policy Sync API** on Felix cluster-wide. +```bash +kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +``` -In the default **FelixConfiguration**, set the field, `policySyncPathPrefix` to `/var/run/nodeagent`: +### 2. Install Istio - - +Follow the [upstream Istio installation documentation](https://istio.io/latest/docs/setup/getting-started/) to install Istio if not already installed. + +For testing, you can use: ```bash -calicoctl patch FelixConfiguration default --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +curl -L https://istio.io/downloadIstio -o install-istio.sh +# Review the script before running it, then install: +ISTIO_VERSION=1.28.1 sh install-istio.sh +cd istio-1.28.1 +export PATH=$PWD/bin:$PATH ``` - - +:::note + +Do not run `istioctl install` yet if you want to configure Dikastes templates during installation. See the next step. + +::: + +### 3. Configure Istio with Dikastes injection templates + +#### Option A: use IstioOperator directly + +Create a file named `istio-operator-dikastes.yaml`: + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +metadata: + name: istio-with-dikastes + namespace: istio-system +spec: + profile: minimal # or 'default' if you need gateways + + values: + sidecarInjectorWebhook: + templates: + # Template for workload pods + dikastes: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 999 + runAsNonRoot: true + runAsUser: 999 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io + + # Template for gateway pods (runs as root) + dikastes-gateway: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 0 + runAsNonRoot: false + runAsUser: 0 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io +``` + +**Install or update Istio** with the Dikastes templates: ```bash -kubectl patch FelixConfiguration default --type=merge --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +istioctl install -f istio-operator-dikastes.yaml -y ``` - - +This will: +- Install Istio (if not already installed) +- Update the `istio-sidecar-injector` ConfigMap with the Dikastes templates +- Make the templates available for pod annotation-based injection -Additionally, if you have installed Calico via the operator, you can optionally disable flexvolumes. -Flexvolumes were used in earlier implementations and have since been deprecated. +**Verify the templates were loaded**: ```bash -kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +kubectl get configmap -n istio-system istio-sidecar-injector -o yaml | grep "dikastes:" -A 5 +``` + +You should see both `dikastes` and `dikastes-gateway` templates. + +#### Option B: Generate Manifests for GitOps + +If you prefer to generate Kubernetes manifests instead of applying directly: + +```bash +istioctl manifest generate -f istio-operator-dikastes.yaml > istio-with-dikastes.yaml +kubectl apply -f istio-with-dikastes.yaml ``` -### Install Calico CSI Driver +### 4. Add Envoy authorization services -$[prodname] utilizes a Container Storage Interface (CSI) driver to help set up the policy sync API on every node. -Apply the following to install the Calico CSI driver +Configure Istio's Envoy proxies to use Dikastes as an external authorization service. ```bash -kubectl apply -f $[manifestsUrl]/manifests/csi-driver.yaml +kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) + +This manifest creates: +- **ServiceEntry**: Defines `dikastes.calico.cluster.local` for Unix socket communication +- **DestinationRule**: Disables mTLS for local socket communication +- **EnvoyFilter**: Configures Envoy's External Authorization filter to call Dikastes + +### 5. Enable Istio injection for namespaces + +Label the namespace where you want to deploy Istio-enabled workloads: + +```bash +kubectl label namespace istio-injection=enabled +``` + +### 6. Annotate pods to inject Dikastes + +To inject the Dikastes sidecar into your pods, add the following annotation to your pod template: + +**For regular workloads**: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp +spec: + template: + metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes + spec: + # ... your pod spec +``` + +**For gateway workloads**: + +```yaml +metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes-gateway ``` -### Install Istio +The key difference: +- `dikastes`: Runs as non-root user (999) - for application workloads +- `dikastes-gateway`: Runs as root (0) - for ingress/egress gateways -1. Verify [application layer policy requirements](../../getting-started/kubernetes/requirements.mdx#application-layer-policy-requirements). -2. Install Istio using [installation guide in the project documentation](https://istio.io/v1.15/docs/setup/install/). +### 7. Verify Dikastes injection + +After deploying a workload with the annotation: ```bash -curl -L https://git.io/getLatestIstio | ISTIO_VERSION=1.15.2 sh - -cd $(ls -d istio-* --color=never) -./bin/istioctl install +# Check that Dikastes container is present +kubectl get pod -l app= -n -o jsonpath='{.items[0].spec.containers[*].name}' ``` -Next, create the following [PeerAuthentication](https://istio.io/v1.15/docs/reference/config/security/peer_authentication/) policy. +You should see: `dikastes ...` -Replace `namespace` below by `rootNamespace` value, if it's customized in your environment. +**Check pod status** (should show all containers ready): ```bash -kubectl create -f - < +``` + +**Check Dikastes logs**: + +```bash +kubectl logs -n -l app= -c dikastes +``` + +You should see: +``` +Successfully connected to Policy Sync server +Starting synchronization with Policy Sync server +``` + +### 8. (Optional) Enable strict mTLS + +For enhanced security, enable strict mutual TLS between services: + +```yaml apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: @@ -128,75 +335,176 @@ metadata: spec: mtls: mode: STRICT -EOF ``` -### Update Istio sidecar injector +Apply: -The sidecar injector automatically modifies pods as they are created to work with Istio. This step modifies the injector configuration to add Dikastes (a $[prodname] component), as sidecar containers. +```bash +kubectl apply -f .yaml +``` -1. Follow the [Automatic sidecar injection instructions](https://archive.istio.io/v1.15/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) to install the sidecar injector and enable it in your chosen namespace(s). -2. Patch the istio-sidecar-injector `ConfigMap` to enable injection of Dikastes alongside Envoy. +## Create Calico network policies - - +With Dikastes deployed, you can now create $[prodname] network policies to enforce Layer 7 access control. + +:::note + +The specific policy Custom Resource Definitions available depend on your $[prodname] distribution (OSS vs Enterprise). Consult your $[prodname] documentation for policy syntax. + +::: + +Example conceptual policy (syntax may vary): + +```yaml +apiVersion: projectcalico.org/v3 +kind: NetworkPolicy +metadata: + name: allow-http-get + namespace: default +spec: + selector: app == "myapp" + types: + - Ingress + ingress: + - action: Allow + protocol: TCP + destination: + ports: + - 80 +``` + +### Default behavior + +Without explicit allow policies, Dikastes enforces a **default-deny** posture for security. All HTTP requests will receive a `403 Forbidden` response until you create policies that explicitly allow traffic. + +## Troubleshooting + +### Dikastes container not injected + +**Check namespace label**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get namespace -o jsonpath='{.metadata.labels.istio-injection}' ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) +Should show: `enabled` - - +**Check pod annotation**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get pod -n -o yaml | grep inject.istio.io/templates ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) +Should show: `inject.istio.io/templates: sidecar,dikastes` - - +**Verify templates in ConfigMap**: -### Add Calico authorization services to the mesh +```bash +kubectl get configmap -n istio-system istio-sidecar-injector -o jsonpath='{.data.values}' | grep -o "dikastes:" | wc -l +``` + +Should return `2` (one for each template). -Apply the following manifest to configure Istio to query $[prodname] for application layer policy authorization decisions. +### Pod stuck in PodInitializing or CrashLoopBackOff -This applies to Istio v1.15.x and v1.10.x: +**Check pod events**: ```bash -kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +kubectl describe pod -n ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) +**Check Dikastes logs**: -### Add namespace labels +```bash +kubectl logs -n -c dikastes +``` + +**Check CSI driver** (automatically installed with $[prodname]): + +```bash +kubectl get pods -n calico-system -l k8s-app=csi-node-driver +``` -You can control enforcement of application layer policy on a per-namespace basis. However, this only works on pods that are started with the Envoy and $[prodname] Dikastes sidecars (as noted in the step, Update Istio sidecar injector). Pods that do not have the $[prodname] sidecars, enforce only standard $[prodname] network policy. +All CSI driver pods should be `Running`. The CSI driver is required for Dikastes to access the Felix Policy Sync API. -To enable Istio and application layer policy in a namespace, add the label `istio-injection=enabled`. +**Verify Felix Policy Sync API**: ```bash -kubectl label namespace istio-injection=enabled +kubectl get felixconfiguration default -o yaml | grep policySyncPathPrefix ``` -If the namespace already has pods in it, you must recreate them for this to take effect. +Should show: `policySyncPathPrefix: /var/run/nodeagent` -:::note +### All requests returning 403 + +This is **expected behavior** when no allow policies are configured. Dikastes enforces default-deny for security. + +To allow traffic, create $[prodname] network policies that explicitly permit the desired traffic. + +### Envoy cannot reach istio-pilot -Envoy must be able to communicate with the `istio-pilot.istio-system service`. If you apply any egress policies to your pods, you _must_ enable access. +If you have egress policies applied to your pods, Envoy needs access to the Istio control plane. + +Apply the allow policy: ```bash kubectl apply -f $[tutorialFilesURL]/allow-istio-pilot.yaml ``` +### Warning about BPF load balancing + +If you see this warning during installation: + +``` +detected Calico CNI with 'bpfConnectTimeLoadBalancing=TCP'; +this must be set to 'bpfConnectTimeLoadBalancing=Disabled' +``` + +This may affect connection-level load balancing but does not prevent basic functionality. For production deployments, disable BPF connect-time load balancing: + +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"bpfConnectTimeLoadBalancing":"Disabled"}}' +``` + +## Legacy Installation (ConfigMap Patching) + +:::note + +This method is supported but not recommended for new deployments. Use the IstioOperator method instead. + ::: +If you need to use the legacy ConfigMap patching method for Istio 1.15 or 1.10: + +### For Istio v1.15.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) + +### For Istio v1.10.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) + +**Drawbacks of ConfigMap patching**: + +- Not declarative (imperative command) +- Not version-controlled +- Must be re-applied after Istio upgrades +- Difficult to audit and review + ## Additional resources - [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) - [Use HTTP methods and paths in policy rules](http-methods.mdx) -- [Hands-on workshop: Learn how to deploy access control, encryption & auth at the application level](https://www.tigera.io/tutorials/?_sf_s=Deploy%20Service%20Mesh) +- [Istio Documentation](https://istio.io/latest/docs/) +- [IstioOperator API Reference](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) +- [Kubernetes Native Sidecars](https://kubernetes.io/blog/2023/08/25/native-sidecar-containers/) diff --git a/calico_versioned_docs/version-3.29/network-policy/istio/app-layer-policy.mdx b/calico_versioned_docs/version-3.29/network-policy/istio/app-layer-policy.mdx index e9c3751677..9c3d6c5712 100644 --- a/calico_versioned_docs/version-3.29/network-policy/istio/app-layer-policy.mdx +++ b/calico_versioned_docs/version-3.29/network-policy/istio/app-layer-policy.mdx @@ -4,122 +4,329 @@ description: Enforce network policy for Istio service mesh including matching on import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Enforce network policy for Istio +# Enforce Calico network policy for Istio service mesh -## Big picture +## Overview -$[prodname] integrates seamlessly with Istio to enforce network policy within the Istio service mesh. +You can enforce $[prodname] network policy for Istio application layer policy using the Dikastes sidecar. Dikastes enables $[prodname] to integrate with Istio's Envoy proxy to enforce fine-grained Layer 7 (HTTP) policies. -## Value +### Value -$[prodname] network policy for Istio lets you enforce application layer attributes like HTTP methods or paths, and cryptographically secure identities for Istio-enabled apps. +- **Pod traffic controls for Istio-enabled apps**: Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Security alignment with zero trust**: Supports zero-trust network models through traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +- **Familiar policy language**: Apply Kubernetes network policies and $[prodname] network policies that you already know. -## Concepts +## Before you begin -### Benefits of the Istio integration +**Required** -The $[prodname] support for Istio service mesh has the following benefits: +- $[prodname] CNI is installed and configured +- `kubectl` and `istioctl` CLI tools are installed +- MutatingAdmissionWebhook admission controller is enabled -- **Pod traffic controls** +**Supported Istio versions** - Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Istio v1.28.1** (recommended) +- **Istio v1.22+** (minimum required for Kubernetes native sidecar support) -- **Supports security goals** +:::note - Enables adoption of a zero trust network model for security, including traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +This guide requires Istio 1.22+ with Kubernetes native sidecars. Traditional sidecar injection is not supported. For legacy Istio versions (v1.15.2, v1.10.2), see [Legacy Installation](#legacy-installation-configmap-patching). -- **Familiar policy language** +::: - Kubernetes network policies and $[prodname] network policies work as is; users do not need to learn another network policy model to adopt Istio. +**Required Kubernetes versions** -See [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) to learn how application layer policy provides second-factor authentication for the mythical Yao Bank. +- **Kubernetes v1.29+**: Required for native sidecar support -## Before you begin +## How to -**Required** +This guide covers the usage of [IstioOperator](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) -- [$[prodname] is installed](../../getting-started/index.mdx) -- [calicoctl is installed and configured](../../operations/calicoctl/install.mdx) -- [MutatingAdmissionWebhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) enabled +For the ConfigMap patching method, see [Legacy Installation](#legacy-installation-configmap-patching). -**Istio support** +### 1. Enable application layer policy -Following Istio versions have been verified to work with application layer policies: +Enable the Policy Sync API in Felix to allow Dikastes to query policy decisions. -- Istio v1.15.2 -- Istio v1.10.2 + + -Istio v1.9.x and lower are **not** supported. +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"policySyncPathPrefix":"/var/run/nodeagent"}}' +``` -Although we expect future minor versions to work with the corresponding manifest below (for example, v1.10.2 or v1.15.2), manifest compatibility depends entirely on the upstream changes in the respective Istio release. + + -## How to +```bash +calicoctl patch FelixConfiguration default --patch \ + '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +``` -1. [Enable application layer policy](#enable-application-layer-policy) -2. [Install Calico CSI Driver](#install-calico-csi-driver) -3. [Install Istio](#install-istio) -4. [Update Istio sidecar injector](#update-istio-sidecar-injector) -5. [Add Calico authorization services to the mesh](#add-calico-authorization-services-to-the-mesh) -6. [Add namespace labels](#add-namespace-labels) + + -### Enable application layer policy +**Optional**: If using the $[prodname] operator, disable deprecated Flex Volumes: -To enable the application layer policy, you must enable the **Policy Sync API** on Felix cluster-wide. +```bash +kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +``` -In the default **FelixConfiguration**, set the field, `policySyncPathPrefix` to `/var/run/nodeagent`: +### 2. Install Istio - - +Follow the [upstream Istio installation documentation](https://istio.io/latest/docs/setup/getting-started/) to install Istio if not already installed. + +For testing, you can use: ```bash -calicoctl patch FelixConfiguration default --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +curl -L https://istio.io/downloadIstio -o install-istio.sh +# Review the script before running it, then install: +ISTIO_VERSION=1.28.1 sh install-istio.sh +cd istio-1.28.1 +export PATH=$PWD/bin:$PATH ``` - - +:::note + +Do not run `istioctl install` yet if you want to configure Dikastes templates during installation. See the next step. + +::: + +### 3. Configure Istio with Dikastes injection templates + +#### Option A: use IstioOperator directly + +Create a file named `istio-operator-dikastes.yaml`: + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +metadata: + name: istio-with-dikastes + namespace: istio-system +spec: + profile: minimal # or 'default' if you need gateways + + values: + sidecarInjectorWebhook: + templates: + # Template for workload pods + dikastes: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 999 + runAsNonRoot: true + runAsUser: 999 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io + + # Template for gateway pods (runs as root) + dikastes-gateway: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 0 + runAsNonRoot: false + runAsUser: 0 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io +``` + +**Install or update Istio** with the Dikastes templates: ```bash -kubectl patch FelixConfiguration default --type=merge --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +istioctl install -f istio-operator-dikastes.yaml -y ``` - - +This will: +- Install Istio (if not already installed) +- Update the `istio-sidecar-injector` ConfigMap with the Dikastes templates +- Make the templates available for pod annotation-based injection -Additionally, if you have installed Calico via the operator, you can optionally disable flexvolumes. -Flexvolumes were used in earlier implementations and have since been deprecated. +**Verify the templates were loaded**: ```bash -kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +kubectl get configmap -n istio-system istio-sidecar-injector -o yaml | grep "dikastes:" -A 5 +``` + +You should see both `dikastes` and `dikastes-gateway` templates. + +#### Option B: Generate Manifests for GitOps + +If you prefer to generate Kubernetes manifests instead of applying directly: + +```bash +istioctl manifest generate -f istio-operator-dikastes.yaml > istio-with-dikastes.yaml +kubectl apply -f istio-with-dikastes.yaml ``` -### Install Calico CSI Driver +### 4. Add Envoy authorization services -$[prodname] utilizes a Container Storage Interface (CSI) driver to help set up the policy sync API on every node. -Apply the following to install the Calico CSI driver +Configure Istio's Envoy proxies to use Dikastes as an external authorization service. ```bash -kubectl apply -f $[manifestsUrl]/manifests/csi-driver.yaml +kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) + +This manifest creates: +- **ServiceEntry**: Defines `dikastes.calico.cluster.local` for Unix socket communication +- **DestinationRule**: Disables mTLS for local socket communication +- **EnvoyFilter**: Configures Envoy's External Authorization filter to call Dikastes + +### 5. Enable Istio injection for namespaces + +Label the namespace where you want to deploy Istio-enabled workloads: + +```bash +kubectl label namespace istio-injection=enabled +``` + +### 6. Annotate pods to inject Dikastes + +To inject the Dikastes sidecar into your pods, add the following annotation to your pod template: + +**For regular workloads**: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp +spec: + template: + metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes + spec: + # ... your pod spec +``` + +**For gateway workloads**: + +```yaml +metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes-gateway ``` -### Install Istio +The key difference: +- `dikastes`: Runs as non-root user (999) - for application workloads +- `dikastes-gateway`: Runs as root (0) - for ingress/egress gateways -1. Verify [application layer policy requirements](../../getting-started/kubernetes/requirements.mdx#application-layer-policy-requirements). -2. Install Istio using [installation guide in the project documentation](https://istio.io/v1.15/docs/setup/install/). +### 7. Verify Dikastes injection + +After deploying a workload with the annotation: ```bash -curl -L https://git.io/getLatestIstio | ISTIO_VERSION=1.15.2 sh - -cd $(ls -d istio-* --color=never) -./bin/istioctl install +# Check that Dikastes container is present +kubectl get pod -l app= -n -o jsonpath='{.items[0].spec.containers[*].name}' ``` -Next, create the following [PeerAuthentication](https://istio.io/v1.15/docs/reference/config/security/peer_authentication/) policy. +You should see: `dikastes ...` -Replace `namespace` below by `rootNamespace` value, if it's customized in your environment. +**Check pod status** (should show all containers ready): ```bash -kubectl create -f - < +``` + +**Check Dikastes logs**: + +```bash +kubectl logs -n -l app= -c dikastes +``` + +You should see: +``` +Successfully connected to Policy Sync server +Starting synchronization with Policy Sync server +``` + +### 8. (Optional) Enable strict mTLS + +For enhanced security, enable strict mutual TLS between services: + +```yaml apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: @@ -128,75 +335,176 @@ metadata: spec: mtls: mode: STRICT -EOF ``` -### Update Istio sidecar injector +Apply: -The sidecar injector automatically modifies pods as they are created to work with Istio. This step modifies the injector configuration to add Dikastes (a $[prodname] component), as sidecar containers. +```bash +kubectl apply -f .yaml +``` -1. Follow the [Automatic sidecar injection instructions](https://archive.istio.io/v1.15/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) to install the sidecar injector and enable it in your chosen namespace(s). -2. Patch the istio-sidecar-injector `ConfigMap` to enable injection of Dikastes alongside Envoy. +## Create Calico network policies - - +With Dikastes deployed, you can now create $[prodname] network policies to enforce Layer 7 access control. + +:::note + +The specific policy Custom Resource Definitions available depend on your $[prodname] distribution (OSS vs Enterprise). Consult your $[prodname] documentation for policy syntax. + +::: + +Example conceptual policy (syntax may vary): + +```yaml +apiVersion: projectcalico.org/v3 +kind: NetworkPolicy +metadata: + name: allow-http-get + namespace: default +spec: + selector: app == "myapp" + types: + - Ingress + ingress: + - action: Allow + protocol: TCP + destination: + ports: + - 80 +``` + +### Default behavior + +Without explicit allow policies, Dikastes enforces a **default-deny** posture for security. All HTTP requests will receive a `403 Forbidden` response until you create policies that explicitly allow traffic. + +## Troubleshooting + +### Dikastes container not injected + +**Check namespace label**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get namespace -o jsonpath='{.metadata.labels.istio-injection}' ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) +Should show: `enabled` - - +**Check pod annotation**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get pod -n -o yaml | grep inject.istio.io/templates ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) +Should show: `inject.istio.io/templates: sidecar,dikastes` - - +**Verify templates in ConfigMap**: -### Add Calico authorization services to the mesh +```bash +kubectl get configmap -n istio-system istio-sidecar-injector -o jsonpath='{.data.values}' | grep -o "dikastes:" | wc -l +``` + +Should return `2` (one for each template). -Apply the following manifest to configure Istio to query $[prodname] for application layer policy authorization decisions. +### Pod stuck in PodInitializing or CrashLoopBackOff -This applies to Istio v1.15.x and v1.10.x: +**Check pod events**: ```bash -kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +kubectl describe pod -n ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) +**Check Dikastes logs**: -### Add namespace labels +```bash +kubectl logs -n -c dikastes +``` + +**Check CSI driver** (automatically installed with $[prodname]): + +```bash +kubectl get pods -n calico-system -l k8s-app=csi-node-driver +``` -You can control enforcement of application layer policy on a per-namespace basis. However, this only works on pods that are started with the Envoy and $[prodname] Dikastes sidecars (as noted in the step, Update Istio sidecar injector). Pods that do not have the $[prodname] sidecars, enforce only standard $[prodname] network policy. +All CSI driver pods should be `Running`. The CSI driver is required for Dikastes to access the Felix Policy Sync API. -To enable Istio and application layer policy in a namespace, add the label `istio-injection=enabled`. +**Verify Felix Policy Sync API**: ```bash -kubectl label namespace istio-injection=enabled +kubectl get felixconfiguration default -o yaml | grep policySyncPathPrefix ``` -If the namespace already has pods in it, you must recreate them for this to take effect. +Should show: `policySyncPathPrefix: /var/run/nodeagent` -:::note +### All requests returning 403 + +This is **expected behavior** when no allow policies are configured. Dikastes enforces default-deny for security. + +To allow traffic, create $[prodname] network policies that explicitly permit the desired traffic. + +### Envoy cannot reach istio-pilot -Envoy must be able to communicate with the `istio-pilot.istio-system service`. If you apply any egress policies to your pods, you _must_ enable access. +If you have egress policies applied to your pods, Envoy needs access to the Istio control plane. + +Apply the allow policy: ```bash kubectl apply -f $[tutorialFilesURL]/allow-istio-pilot.yaml ``` +### Warning about BPF load balancing + +If you see this warning during installation: + +``` +detected Calico CNI with 'bpfConnectTimeLoadBalancing=TCP'; +this must be set to 'bpfConnectTimeLoadBalancing=Disabled' +``` + +This may affect connection-level load balancing but does not prevent basic functionality. For production deployments, disable BPF connect-time load balancing: + +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"bpfConnectTimeLoadBalancing":"Disabled"}}' +``` + +## Legacy Installation (ConfigMap Patching) + +:::note + +This method is supported but not recommended for new deployments. Use the IstioOperator method instead. + ::: +If you need to use the legacy ConfigMap patching method for Istio 1.15 or 1.10: + +### For Istio v1.15.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) + +### For Istio v1.10.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) + +**Drawbacks of ConfigMap patching**: + +- Not declarative (imperative command) +- Not version-controlled +- Must be re-applied after Istio upgrades +- Difficult to audit and review + ## Additional resources - [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) - [Use HTTP methods and paths in policy rules](http-methods.mdx) -- [Hands-on workshop: Learn how to deploy access control, encryption & auth at the application level](https://www.tigera.io/tutorials/?_sf_s=Deploy%20Service%20Mesh) +- [Istio Documentation](https://istio.io/latest/docs/) +- [IstioOperator API Reference](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) +- [Kubernetes Native Sidecars](https://kubernetes.io/blog/2023/08/25/native-sidecar-containers/) diff --git a/calico_versioned_docs/version-3.30/network-policy/istio/app-layer-policy.mdx b/calico_versioned_docs/version-3.30/network-policy/istio/app-layer-policy.mdx index e9c3751677..9c3d6c5712 100644 --- a/calico_versioned_docs/version-3.30/network-policy/istio/app-layer-policy.mdx +++ b/calico_versioned_docs/version-3.30/network-policy/istio/app-layer-policy.mdx @@ -4,122 +4,329 @@ description: Enforce network policy for Istio service mesh including matching on import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Enforce network policy for Istio +# Enforce Calico network policy for Istio service mesh -## Big picture +## Overview -$[prodname] integrates seamlessly with Istio to enforce network policy within the Istio service mesh. +You can enforce $[prodname] network policy for Istio application layer policy using the Dikastes sidecar. Dikastes enables $[prodname] to integrate with Istio's Envoy proxy to enforce fine-grained Layer 7 (HTTP) policies. -## Value +### Value -$[prodname] network policy for Istio lets you enforce application layer attributes like HTTP methods or paths, and cryptographically secure identities for Istio-enabled apps. +- **Pod traffic controls for Istio-enabled apps**: Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Security alignment with zero trust**: Supports zero-trust network models through traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +- **Familiar policy language**: Apply Kubernetes network policies and $[prodname] network policies that you already know. -## Concepts +## Before you begin -### Benefits of the Istio integration +**Required** -The $[prodname] support for Istio service mesh has the following benefits: +- $[prodname] CNI is installed and configured +- `kubectl` and `istioctl` CLI tools are installed +- MutatingAdmissionWebhook admission controller is enabled -- **Pod traffic controls** +**Supported Istio versions** - Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Istio v1.28.1** (recommended) +- **Istio v1.22+** (minimum required for Kubernetes native sidecar support) -- **Supports security goals** +:::note - Enables adoption of a zero trust network model for security, including traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +This guide requires Istio 1.22+ with Kubernetes native sidecars. Traditional sidecar injection is not supported. For legacy Istio versions (v1.15.2, v1.10.2), see [Legacy Installation](#legacy-installation-configmap-patching). -- **Familiar policy language** +::: - Kubernetes network policies and $[prodname] network policies work as is; users do not need to learn another network policy model to adopt Istio. +**Required Kubernetes versions** -See [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) to learn how application layer policy provides second-factor authentication for the mythical Yao Bank. +- **Kubernetes v1.29+**: Required for native sidecar support -## Before you begin +## How to -**Required** +This guide covers the usage of [IstioOperator](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) -- [$[prodname] is installed](../../getting-started/index.mdx) -- [calicoctl is installed and configured](../../operations/calicoctl/install.mdx) -- [MutatingAdmissionWebhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) enabled +For the ConfigMap patching method, see [Legacy Installation](#legacy-installation-configmap-patching). -**Istio support** +### 1. Enable application layer policy -Following Istio versions have been verified to work with application layer policies: +Enable the Policy Sync API in Felix to allow Dikastes to query policy decisions. -- Istio v1.15.2 -- Istio v1.10.2 + + -Istio v1.9.x and lower are **not** supported. +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"policySyncPathPrefix":"/var/run/nodeagent"}}' +``` -Although we expect future minor versions to work with the corresponding manifest below (for example, v1.10.2 or v1.15.2), manifest compatibility depends entirely on the upstream changes in the respective Istio release. + + -## How to +```bash +calicoctl patch FelixConfiguration default --patch \ + '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +``` -1. [Enable application layer policy](#enable-application-layer-policy) -2. [Install Calico CSI Driver](#install-calico-csi-driver) -3. [Install Istio](#install-istio) -4. [Update Istio sidecar injector](#update-istio-sidecar-injector) -5. [Add Calico authorization services to the mesh](#add-calico-authorization-services-to-the-mesh) -6. [Add namespace labels](#add-namespace-labels) + + -### Enable application layer policy +**Optional**: If using the $[prodname] operator, disable deprecated Flex Volumes: -To enable the application layer policy, you must enable the **Policy Sync API** on Felix cluster-wide. +```bash +kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +``` -In the default **FelixConfiguration**, set the field, `policySyncPathPrefix` to `/var/run/nodeagent`: +### 2. Install Istio - - +Follow the [upstream Istio installation documentation](https://istio.io/latest/docs/setup/getting-started/) to install Istio if not already installed. + +For testing, you can use: ```bash -calicoctl patch FelixConfiguration default --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +curl -L https://istio.io/downloadIstio -o install-istio.sh +# Review the script before running it, then install: +ISTIO_VERSION=1.28.1 sh install-istio.sh +cd istio-1.28.1 +export PATH=$PWD/bin:$PATH ``` - - +:::note + +Do not run `istioctl install` yet if you want to configure Dikastes templates during installation. See the next step. + +::: + +### 3. Configure Istio with Dikastes injection templates + +#### Option A: use IstioOperator directly + +Create a file named `istio-operator-dikastes.yaml`: + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +metadata: + name: istio-with-dikastes + namespace: istio-system +spec: + profile: minimal # or 'default' if you need gateways + + values: + sidecarInjectorWebhook: + templates: + # Template for workload pods + dikastes: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 999 + runAsNonRoot: true + runAsUser: 999 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io + + # Template for gateway pods (runs as root) + dikastes-gateway: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 0 + runAsNonRoot: false + runAsUser: 0 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io +``` + +**Install or update Istio** with the Dikastes templates: ```bash -kubectl patch FelixConfiguration default --type=merge --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +istioctl install -f istio-operator-dikastes.yaml -y ``` - - +This will: +- Install Istio (if not already installed) +- Update the `istio-sidecar-injector` ConfigMap with the Dikastes templates +- Make the templates available for pod annotation-based injection -Additionally, if you have installed Calico via the operator, you can optionally disable flexvolumes. -Flexvolumes were used in earlier implementations and have since been deprecated. +**Verify the templates were loaded**: ```bash -kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +kubectl get configmap -n istio-system istio-sidecar-injector -o yaml | grep "dikastes:" -A 5 +``` + +You should see both `dikastes` and `dikastes-gateway` templates. + +#### Option B: Generate Manifests for GitOps + +If you prefer to generate Kubernetes manifests instead of applying directly: + +```bash +istioctl manifest generate -f istio-operator-dikastes.yaml > istio-with-dikastes.yaml +kubectl apply -f istio-with-dikastes.yaml ``` -### Install Calico CSI Driver +### 4. Add Envoy authorization services -$[prodname] utilizes a Container Storage Interface (CSI) driver to help set up the policy sync API on every node. -Apply the following to install the Calico CSI driver +Configure Istio's Envoy proxies to use Dikastes as an external authorization service. ```bash -kubectl apply -f $[manifestsUrl]/manifests/csi-driver.yaml +kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) + +This manifest creates: +- **ServiceEntry**: Defines `dikastes.calico.cluster.local` for Unix socket communication +- **DestinationRule**: Disables mTLS for local socket communication +- **EnvoyFilter**: Configures Envoy's External Authorization filter to call Dikastes + +### 5. Enable Istio injection for namespaces + +Label the namespace where you want to deploy Istio-enabled workloads: + +```bash +kubectl label namespace istio-injection=enabled +``` + +### 6. Annotate pods to inject Dikastes + +To inject the Dikastes sidecar into your pods, add the following annotation to your pod template: + +**For regular workloads**: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp +spec: + template: + metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes + spec: + # ... your pod spec +``` + +**For gateway workloads**: + +```yaml +metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes-gateway ``` -### Install Istio +The key difference: +- `dikastes`: Runs as non-root user (999) - for application workloads +- `dikastes-gateway`: Runs as root (0) - for ingress/egress gateways -1. Verify [application layer policy requirements](../../getting-started/kubernetes/requirements.mdx#application-layer-policy-requirements). -2. Install Istio using [installation guide in the project documentation](https://istio.io/v1.15/docs/setup/install/). +### 7. Verify Dikastes injection + +After deploying a workload with the annotation: ```bash -curl -L https://git.io/getLatestIstio | ISTIO_VERSION=1.15.2 sh - -cd $(ls -d istio-* --color=never) -./bin/istioctl install +# Check that Dikastes container is present +kubectl get pod -l app= -n -o jsonpath='{.items[0].spec.containers[*].name}' ``` -Next, create the following [PeerAuthentication](https://istio.io/v1.15/docs/reference/config/security/peer_authentication/) policy. +You should see: `dikastes ...` -Replace `namespace` below by `rootNamespace` value, if it's customized in your environment. +**Check pod status** (should show all containers ready): ```bash -kubectl create -f - < +``` + +**Check Dikastes logs**: + +```bash +kubectl logs -n -l app= -c dikastes +``` + +You should see: +``` +Successfully connected to Policy Sync server +Starting synchronization with Policy Sync server +``` + +### 8. (Optional) Enable strict mTLS + +For enhanced security, enable strict mutual TLS between services: + +```yaml apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: @@ -128,75 +335,176 @@ metadata: spec: mtls: mode: STRICT -EOF ``` -### Update Istio sidecar injector +Apply: -The sidecar injector automatically modifies pods as they are created to work with Istio. This step modifies the injector configuration to add Dikastes (a $[prodname] component), as sidecar containers. +```bash +kubectl apply -f .yaml +``` -1. Follow the [Automatic sidecar injection instructions](https://archive.istio.io/v1.15/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) to install the sidecar injector and enable it in your chosen namespace(s). -2. Patch the istio-sidecar-injector `ConfigMap` to enable injection of Dikastes alongside Envoy. +## Create Calico network policies - - +With Dikastes deployed, you can now create $[prodname] network policies to enforce Layer 7 access control. + +:::note + +The specific policy Custom Resource Definitions available depend on your $[prodname] distribution (OSS vs Enterprise). Consult your $[prodname] documentation for policy syntax. + +::: + +Example conceptual policy (syntax may vary): + +```yaml +apiVersion: projectcalico.org/v3 +kind: NetworkPolicy +metadata: + name: allow-http-get + namespace: default +spec: + selector: app == "myapp" + types: + - Ingress + ingress: + - action: Allow + protocol: TCP + destination: + ports: + - 80 +``` + +### Default behavior + +Without explicit allow policies, Dikastes enforces a **default-deny** posture for security. All HTTP requests will receive a `403 Forbidden` response until you create policies that explicitly allow traffic. + +## Troubleshooting + +### Dikastes container not injected + +**Check namespace label**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get namespace -o jsonpath='{.metadata.labels.istio-injection}' ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) +Should show: `enabled` - - +**Check pod annotation**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get pod -n -o yaml | grep inject.istio.io/templates ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) +Should show: `inject.istio.io/templates: sidecar,dikastes` - - +**Verify templates in ConfigMap**: -### Add Calico authorization services to the mesh +```bash +kubectl get configmap -n istio-system istio-sidecar-injector -o jsonpath='{.data.values}' | grep -o "dikastes:" | wc -l +``` + +Should return `2` (one for each template). -Apply the following manifest to configure Istio to query $[prodname] for application layer policy authorization decisions. +### Pod stuck in PodInitializing or CrashLoopBackOff -This applies to Istio v1.15.x and v1.10.x: +**Check pod events**: ```bash -kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +kubectl describe pod -n ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) +**Check Dikastes logs**: -### Add namespace labels +```bash +kubectl logs -n -c dikastes +``` + +**Check CSI driver** (automatically installed with $[prodname]): + +```bash +kubectl get pods -n calico-system -l k8s-app=csi-node-driver +``` -You can control enforcement of application layer policy on a per-namespace basis. However, this only works on pods that are started with the Envoy and $[prodname] Dikastes sidecars (as noted in the step, Update Istio sidecar injector). Pods that do not have the $[prodname] sidecars, enforce only standard $[prodname] network policy. +All CSI driver pods should be `Running`. The CSI driver is required for Dikastes to access the Felix Policy Sync API. -To enable Istio and application layer policy in a namespace, add the label `istio-injection=enabled`. +**Verify Felix Policy Sync API**: ```bash -kubectl label namespace istio-injection=enabled +kubectl get felixconfiguration default -o yaml | grep policySyncPathPrefix ``` -If the namespace already has pods in it, you must recreate them for this to take effect. +Should show: `policySyncPathPrefix: /var/run/nodeagent` -:::note +### All requests returning 403 + +This is **expected behavior** when no allow policies are configured. Dikastes enforces default-deny for security. + +To allow traffic, create $[prodname] network policies that explicitly permit the desired traffic. + +### Envoy cannot reach istio-pilot -Envoy must be able to communicate with the `istio-pilot.istio-system service`. If you apply any egress policies to your pods, you _must_ enable access. +If you have egress policies applied to your pods, Envoy needs access to the Istio control plane. + +Apply the allow policy: ```bash kubectl apply -f $[tutorialFilesURL]/allow-istio-pilot.yaml ``` +### Warning about BPF load balancing + +If you see this warning during installation: + +``` +detected Calico CNI with 'bpfConnectTimeLoadBalancing=TCP'; +this must be set to 'bpfConnectTimeLoadBalancing=Disabled' +``` + +This may affect connection-level load balancing but does not prevent basic functionality. For production deployments, disable BPF connect-time load balancing: + +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"bpfConnectTimeLoadBalancing":"Disabled"}}' +``` + +## Legacy Installation (ConfigMap Patching) + +:::note + +This method is supported but not recommended for new deployments. Use the IstioOperator method instead. + ::: +If you need to use the legacy ConfigMap patching method for Istio 1.15 or 1.10: + +### For Istio v1.15.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) + +### For Istio v1.10.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) + +**Drawbacks of ConfigMap patching**: + +- Not declarative (imperative command) +- Not version-controlled +- Must be re-applied after Istio upgrades +- Difficult to audit and review + ## Additional resources - [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) - [Use HTTP methods and paths in policy rules](http-methods.mdx) -- [Hands-on workshop: Learn how to deploy access control, encryption & auth at the application level](https://www.tigera.io/tutorials/?_sf_s=Deploy%20Service%20Mesh) +- [Istio Documentation](https://istio.io/latest/docs/) +- [IstioOperator API Reference](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) +- [Kubernetes Native Sidecars](https://kubernetes.io/blog/2023/08/25/native-sidecar-containers/) diff --git a/calico_versioned_docs/version-3.31/network-policy/istio/app-layer-policy.mdx b/calico_versioned_docs/version-3.31/network-policy/istio/app-layer-policy.mdx index e9c3751677..9c3d6c5712 100644 --- a/calico_versioned_docs/version-3.31/network-policy/istio/app-layer-policy.mdx +++ b/calico_versioned_docs/version-3.31/network-policy/istio/app-layer-policy.mdx @@ -4,122 +4,329 @@ description: Enforce network policy for Istio service mesh including matching on import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Enforce network policy for Istio +# Enforce Calico network policy for Istio service mesh -## Big picture +## Overview -$[prodname] integrates seamlessly with Istio to enforce network policy within the Istio service mesh. +You can enforce $[prodname] network policy for Istio application layer policy using the Dikastes sidecar. Dikastes enables $[prodname] to integrate with Istio's Envoy proxy to enforce fine-grained Layer 7 (HTTP) policies. -## Value +### Value -$[prodname] network policy for Istio lets you enforce application layer attributes like HTTP methods or paths, and cryptographically secure identities for Istio-enabled apps. +- **Pod traffic controls for Istio-enabled apps**: Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Security alignment with zero trust**: Supports zero-trust network models through traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +- **Familiar policy language**: Apply Kubernetes network policies and $[prodname] network policies that you already know. -## Concepts +## Before you begin -### Benefits of the Istio integration +**Required** -The $[prodname] support for Istio service mesh has the following benefits: +- $[prodname] CNI is installed and configured +- `kubectl` and `istioctl` CLI tools are installed +- MutatingAdmissionWebhook admission controller is enabled -- **Pod traffic controls** +**Supported Istio versions** - Lets you restrict ingress traffic inside and outside pods and mitigate common threats to Istio-enabled apps. +- **Istio v1.28.1** (recommended) +- **Istio v1.22+** (minimum required for Kubernetes native sidecar support) -- **Supports security goals** +:::note - Enables adoption of a zero trust network model for security, including traffic encryption, multiple enforcement points, and multiple identity criteria for authentication. +This guide requires Istio 1.22+ with Kubernetes native sidecars. Traditional sidecar injection is not supported. For legacy Istio versions (v1.15.2, v1.10.2), see [Legacy Installation](#legacy-installation-configmap-patching). -- **Familiar policy language** +::: - Kubernetes network policies and $[prodname] network policies work as is; users do not need to learn another network policy model to adopt Istio. +**Required Kubernetes versions** -See [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) to learn how application layer policy provides second-factor authentication for the mythical Yao Bank. +- **Kubernetes v1.29+**: Required for native sidecar support -## Before you begin +## How to -**Required** +This guide covers the usage of [IstioOperator](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) -- [$[prodname] is installed](../../getting-started/index.mdx) -- [calicoctl is installed and configured](../../operations/calicoctl/install.mdx) -- [MutatingAdmissionWebhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) enabled +For the ConfigMap patching method, see [Legacy Installation](#legacy-installation-configmap-patching). -**Istio support** +### 1. Enable application layer policy -Following Istio versions have been verified to work with application layer policies: +Enable the Policy Sync API in Felix to allow Dikastes to query policy decisions. -- Istio v1.15.2 -- Istio v1.10.2 + + -Istio v1.9.x and lower are **not** supported. +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"policySyncPathPrefix":"/var/run/nodeagent"}}' +``` -Although we expect future minor versions to work with the corresponding manifest below (for example, v1.10.2 or v1.15.2), manifest compatibility depends entirely on the upstream changes in the respective Istio release. + + -## How to +```bash +calicoctl patch FelixConfiguration default --patch \ + '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +``` -1. [Enable application layer policy](#enable-application-layer-policy) -2. [Install Calico CSI Driver](#install-calico-csi-driver) -3. [Install Istio](#install-istio) -4. [Update Istio sidecar injector](#update-istio-sidecar-injector) -5. [Add Calico authorization services to the mesh](#add-calico-authorization-services-to-the-mesh) -6. [Add namespace labels](#add-namespace-labels) + + -### Enable application layer policy +**Optional**: If using the $[prodname] operator, disable deprecated Flex Volumes: -To enable the application layer policy, you must enable the **Policy Sync API** on Felix cluster-wide. +```bash +kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +``` -In the default **FelixConfiguration**, set the field, `policySyncPathPrefix` to `/var/run/nodeagent`: +### 2. Install Istio - - +Follow the [upstream Istio installation documentation](https://istio.io/latest/docs/setup/getting-started/) to install Istio if not already installed. + +For testing, you can use: ```bash -calicoctl patch FelixConfiguration default --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +curl -L https://istio.io/downloadIstio -o install-istio.sh +# Review the script before running it, then install: +ISTIO_VERSION=1.28.1 sh install-istio.sh +cd istio-1.28.1 +export PATH=$PWD/bin:$PATH ``` - - +:::note + +Do not run `istioctl install` yet if you want to configure Dikastes templates during installation. See the next step. + +::: + +### 3. Configure Istio with Dikastes injection templates + +#### Option A: use IstioOperator directly + +Create a file named `istio-operator-dikastes.yaml`: + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +metadata: + name: istio-with-dikastes + namespace: istio-system +spec: + profile: minimal # or 'default' if you need gateways + + values: + sidecarInjectorWebhook: + templates: + # Template for workload pods + dikastes: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 999 + runAsNonRoot: true + runAsUser: 999 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io + + # Template for gateway pods (runs as root) + dikastes-gateway: | + spec: + containers: + - name: dikastes + image: quay.io/calico/dikastes:$[version] + args: + - server + - -l + - /var/run/dikastes/dikastes.sock + - -d + - /var/run/felix/nodeagent/socket + securityContext: + allowPrivilegeEscalation: false + runAsGroup: 0 + runAsNonRoot: false + runAsUser: 0 + livenessProbe: + exec: + command: + - /healthz + - liveness + initialDelaySeconds: 3 + periodSeconds: 3 + readinessProbe: + exec: + command: + - /healthz + - readiness + initialDelaySeconds: 3 + periodSeconds: 3 + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + - mountPath: /var/run/felix + name: felix-sync + initContainers: + - name: istio-proxy + volumeMounts: + - mountPath: /var/run/dikastes + name: dikastes-sock + volumes: + - name: dikastes-sock + emptyDir: + medium: Memory + - name: felix-sync + csi: + driver: csi.tigera.io +``` + +**Install or update Istio** with the Dikastes templates: ```bash -kubectl patch FelixConfiguration default --type=merge --patch \ - '{"spec": {"policySyncPathPrefix": "/var/run/nodeagent"}}' +istioctl install -f istio-operator-dikastes.yaml -y ``` - - +This will: +- Install Istio (if not already installed) +- Update the `istio-sidecar-injector` ConfigMap with the Dikastes templates +- Make the templates available for pod annotation-based injection -Additionally, if you have installed Calico via the operator, you can optionally disable flexvolumes. -Flexvolumes were used in earlier implementations and have since been deprecated. +**Verify the templates were loaded**: ```bash -kubectl patch installation default --type=merge -p '{"spec": {"flexVolumePath": "None"}}' +kubectl get configmap -n istio-system istio-sidecar-injector -o yaml | grep "dikastes:" -A 5 +``` + +You should see both `dikastes` and `dikastes-gateway` templates. + +#### Option B: Generate Manifests for GitOps + +If you prefer to generate Kubernetes manifests instead of applying directly: + +```bash +istioctl manifest generate -f istio-operator-dikastes.yaml > istio-with-dikastes.yaml +kubectl apply -f istio-with-dikastes.yaml ``` -### Install Calico CSI Driver +### 4. Add Envoy authorization services -$[prodname] utilizes a Container Storage Interface (CSI) driver to help set up the policy sync API on every node. -Apply the following to install the Calico CSI driver +Configure Istio's Envoy proxies to use Dikastes as an external authorization service. ```bash -kubectl apply -f $[manifestsUrl]/manifests/csi-driver.yaml +kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) + +This manifest creates: +- **ServiceEntry**: Defines `dikastes.calico.cluster.local` for Unix socket communication +- **DestinationRule**: Disables mTLS for local socket communication +- **EnvoyFilter**: Configures Envoy's External Authorization filter to call Dikastes + +### 5. Enable Istio injection for namespaces + +Label the namespace where you want to deploy Istio-enabled workloads: + +```bash +kubectl label namespace istio-injection=enabled +``` + +### 6. Annotate pods to inject Dikastes + +To inject the Dikastes sidecar into your pods, add the following annotation to your pod template: + +**For regular workloads**: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp +spec: + template: + metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes + spec: + # ... your pod spec +``` + +**For gateway workloads**: + +```yaml +metadata: + annotations: + inject.istio.io/templates: sidecar,dikastes-gateway ``` -### Install Istio +The key difference: +- `dikastes`: Runs as non-root user (999) - for application workloads +- `dikastes-gateway`: Runs as root (0) - for ingress/egress gateways -1. Verify [application layer policy requirements](../../getting-started/kubernetes/requirements.mdx#application-layer-policy-requirements). -2. Install Istio using [installation guide in the project documentation](https://istio.io/v1.15/docs/setup/install/). +### 7. Verify Dikastes injection + +After deploying a workload with the annotation: ```bash -curl -L https://git.io/getLatestIstio | ISTIO_VERSION=1.15.2 sh - -cd $(ls -d istio-* --color=never) -./bin/istioctl install +# Check that Dikastes container is present +kubectl get pod -l app= -n -o jsonpath='{.items[0].spec.containers[*].name}' ``` -Next, create the following [PeerAuthentication](https://istio.io/v1.15/docs/reference/config/security/peer_authentication/) policy. +You should see: `dikastes ...` -Replace `namespace` below by `rootNamespace` value, if it's customized in your environment. +**Check pod status** (should show all containers ready): ```bash -kubectl create -f - < +``` + +**Check Dikastes logs**: + +```bash +kubectl logs -n -l app= -c dikastes +``` + +You should see: +``` +Successfully connected to Policy Sync server +Starting synchronization with Policy Sync server +``` + +### 8. (Optional) Enable strict mTLS + +For enhanced security, enable strict mutual TLS between services: + +```yaml apiVersion: security.istio.io/v1beta1 kind: PeerAuthentication metadata: @@ -128,75 +335,176 @@ metadata: spec: mtls: mode: STRICT -EOF ``` -### Update Istio sidecar injector +Apply: -The sidecar injector automatically modifies pods as they are created to work with Istio. This step modifies the injector configuration to add Dikastes (a $[prodname] component), as sidecar containers. +```bash +kubectl apply -f .yaml +``` -1. Follow the [Automatic sidecar injection instructions](https://archive.istio.io/v1.15/docs/setup/additional-setup/sidecar-injection/#automatic-sidecar-injection) to install the sidecar injector and enable it in your chosen namespace(s). -2. Patch the istio-sidecar-injector `ConfigMap` to enable injection of Dikastes alongside Envoy. +## Create Calico network policies - - +With Dikastes deployed, you can now create $[prodname] network policies to enforce Layer 7 access control. + +:::note + +The specific policy Custom Resource Definitions available depend on your $[prodname] distribution (OSS vs Enterprise). Consult your $[prodname] documentation for policy syntax. + +::: + +Example conceptual policy (syntax may vary): + +```yaml +apiVersion: projectcalico.org/v3 +kind: NetworkPolicy +metadata: + name: allow-http-get + namespace: default +spec: + selector: app == "myapp" + types: + - Ingress + ingress: + - action: Allow + protocol: TCP + destination: + ports: + - 80 +``` + +### Default behavior + +Without explicit allow policies, Dikastes enforces a **default-deny** posture for security. All HTTP requests will receive a `403 Forbidden` response until you create policies that explicitly allow traffic. + +## Troubleshooting + +### Dikastes container not injected + +**Check namespace label**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get namespace -o jsonpath='{.metadata.labels.istio-injection}' ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) +Should show: `enabled` - - +**Check pod annotation**: ```bash -curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml -kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +kubectl get pod -n -o yaml | grep inject.istio.io/templates ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) +Should show: `inject.istio.io/templates: sidecar,dikastes` - - +**Verify templates in ConfigMap**: -### Add Calico authorization services to the mesh +```bash +kubectl get configmap -n istio-system istio-sidecar-injector -o jsonpath='{.data.values}' | grep -o "dikastes:" | wc -l +``` + +Should return `2` (one for each template). -Apply the following manifest to configure Istio to query $[prodname] for application layer policy authorization decisions. +### Pod stuck in PodInitializing or CrashLoopBackOff -This applies to Istio v1.15.x and v1.10.x: +**Check pod events**: ```bash -kubectl apply -f $[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml +kubectl describe pod -n ``` -[View sample manifest]($[manifestsUrl]/manifests/alp/istio-app-layer-policy-envoy-v3.yaml) +**Check Dikastes logs**: -### Add namespace labels +```bash +kubectl logs -n -c dikastes +``` + +**Check CSI driver** (automatically installed with $[prodname]): + +```bash +kubectl get pods -n calico-system -l k8s-app=csi-node-driver +``` -You can control enforcement of application layer policy on a per-namespace basis. However, this only works on pods that are started with the Envoy and $[prodname] Dikastes sidecars (as noted in the step, Update Istio sidecar injector). Pods that do not have the $[prodname] sidecars, enforce only standard $[prodname] network policy. +All CSI driver pods should be `Running`. The CSI driver is required for Dikastes to access the Felix Policy Sync API. -To enable Istio and application layer policy in a namespace, add the label `istio-injection=enabled`. +**Verify Felix Policy Sync API**: ```bash -kubectl label namespace istio-injection=enabled +kubectl get felixconfiguration default -o yaml | grep policySyncPathPrefix ``` -If the namespace already has pods in it, you must recreate them for this to take effect. +Should show: `policySyncPathPrefix: /var/run/nodeagent` -:::note +### All requests returning 403 + +This is **expected behavior** when no allow policies are configured. Dikastes enforces default-deny for security. + +To allow traffic, create $[prodname] network policies that explicitly permit the desired traffic. + +### Envoy cannot reach istio-pilot -Envoy must be able to communicate with the `istio-pilot.istio-system service`. If you apply any egress policies to your pods, you _must_ enable access. +If you have egress policies applied to your pods, Envoy needs access to the Istio control plane. + +Apply the allow policy: ```bash kubectl apply -f $[tutorialFilesURL]/allow-istio-pilot.yaml ``` +### Warning about BPF load balancing + +If you see this warning during installation: + +``` +detected Calico CNI with 'bpfConnectTimeLoadBalancing=TCP'; +this must be set to 'bpfConnectTimeLoadBalancing=Disabled' +``` + +This may affect connection-level load balancing but does not prevent basic functionality. For production deployments, disable BPF connect-time load balancing: + +```bash +kubectl patch felixconfiguration default --type merge -p '{"spec":{"bpfConnectTimeLoadBalancing":"Disabled"}}' +``` + +## Legacy Installation (ConfigMap Patching) + +:::note + +This method is supported but not recommended for new deployments. Use the IstioOperator method instead. + ::: +If you need to use the legacy ConfigMap patching method for Istio 1.15 or 1.10: + +### For Istio v1.15.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.15.yaml) + +### For Istio v1.10.x: + +```bash +curl $[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml -o istio-inject-configmap.yaml +kubectl patch configmap -n istio-system istio-sidecar-injector --patch "$(cat istio-inject-configmap.yaml)" +``` + +[View sample manifest]($[manifestsUrl]/manifests/alp/istio-inject-configmap-1.10.yaml) + +**Drawbacks of ConfigMap patching**: + +- Not declarative (imperative command) +- Not version-controlled +- Must be re-applied after Istio upgrades +- Difficult to audit and review + ## Additional resources - [Enforce network policy using Istio tutorial](enforce-policy-istio.mdx) - [Use HTTP methods and paths in policy rules](http-methods.mdx) -- [Hands-on workshop: Learn how to deploy access control, encryption & auth at the application level](https://www.tigera.io/tutorials/?_sf_s=Deploy%20Service%20Mesh) +- [Istio Documentation](https://istio.io/latest/docs/) +- [IstioOperator API Reference](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) +- [Kubernetes Native Sidecars](https://kubernetes.io/blog/2023/08/25/native-sidecar-containers/)