The istios.operator.kyma-project.io CustomResourceDefinition (CRD) describes the kind and the format of data that Istio Controller uses to configure,
update, and manage the Istio installation. Applying the CR triggers the installation of Istio,
and deleting it triggers the uninstallation of Istio. The default Istio CR has the name default.
To get the up-to-date CRD in the yaml format, run the following command:
kubectl get crd istios.operator.kyma-project.io -o yamlYou are only allowed to use one Istio CR, which you must create in the kyma-system namespace.
If the namespace contains multiple Istio CRs, the oldest one reconciles the module.
Any additional Istio CR is placed in the Warning state.
This is a sample Istio CR that configures Istio installation in your Kyma cluster.
apiVersion: operator.kyma-project.io/v1alpha2
kind: Istio
metadata:
name: default
namespace: kyma-system
spec:
config:
gatewayExternalTrafficPolicy: ClusterThe following tables list all the possible parameters of a given resource together with their descriptions.
- operator.kyma-project.io/v1alpha2
Defines an external authorization provider's configuration. The defined authorizer can be referenced by name in an AuthorizationPolicy with action CUSTOM to enforce requests to be authorized by the external authorization service.
Appears in:
| Field | Description | Validation |
|---|---|---|
| name string |
Specifies a unique name identifying the authorization provider. | Required |
| service string |
Specifies the service that implements the Envoy ext_authz HTTP authorization service.The recommended format is [Namespace/]Hostname.Specify the namespace if it is required to unambiguously resolve a service in the service registry. The host name refers to the fully qualified host name of a service defined by either a Kubernetes Service or a ServiceEntry. |
Optional |
| port integer |
Specifies the port of the Service. | Required |
| headers Headers |
Specifies the headers included, added, or forwarded during authorization. | Optional |
| pathPrefix string |
Specifies the prefix included in the request sent to the authorization service. The prefix might be constructed with special characters (for example, /test?original_path=). |
Optional |
| timeout Duration |
Specifies the timeout for the HTTP authorization request to the external service. | Optional |
Configures the Istio CNI DaemonSet component.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s CniK8sConfig |
Configures the Istio CNI DaemonSet component. It is a subset of KubernetesResourcesSpec. | Required |
Configures the Istio CNI DaemonSet component. It is a subset of KubernetesResourcesSpec.
Appears in:
| Field | Description | Validation |
|---|---|---|
| affinity Affinity |
Defines the Pod scheduling affinity constraints. See Affinity and anti-affinity. | Optional |
| resources Resources |
Defines Kubernetes resources' configuration. See Resource Management for Pods and Containers. | Optional |
Appears in:
| Field | Description | Validation |
|---|---|---|
| pilot IstioComponent |
Configures the Istiod component. | Optional |
| ingressGateway IstioComponent |
Configures the Istio Ingress Gateway component. | Optional |
| cni CniComponent |
Configures the Istio CNI DaemonSet component. | Optional |
| proxy ProxyComponent |
Configures the Istio sidecar proxy component. | Optional |
| egressGateway EgressGateway |
Configures the Istio Egress Gateway component. | Optional |
Underlying type: string
| Field | Description |
|---|---|
| ReconcileSucceeded | Reconciliation finished successfully. |
| ReconcileUnknown | Reconciliation is in progress or failed previously. |
| ReconcileRequeued | Reconciliation is requeued to be tried again later. |
| ReconcileFailed | Reconciliation failed. |
| ValidationFailed | Reconciliation did not happen as validation of Istio Custom Resource failed. |
| OlderCRExists | Reconciliation did not happen because an older Istio CR exists. |
| OldestCRNotFound | Reconciliation did not happen as the oldest Istio Custom Resource could not be found. |
| IstioInstallNotNeeded | Istio installation is not needed. |
| IstioInstallSucceeded | Istio installation or uninstallation succeeded. |
| IstioUninstallSucceeded | Istio uninstallation succeeded. |
| IstioInstallUninstallFailed | Istio installation or uninstallation failed. |
| IstioCustomResourceMisconfigured | The Istio custom resource has invalid configuration. |
| IstioCustomResourcesDangling | Istio custom resources are blocking Istio uninstallation. |
| IstioVersionUpdateNotAllowed | Istio version update is not allowed. |
| CustomResourcesReconcileSucceeded | Reconciliation of custom resources succeeded. |
| CustomResourcesReconcileFailed | Reconciliation of custom resources failed. |
| ProxySidecarRestartSucceeded | Proxy sidecar restart succeeded. |
| ProxySidecarRestartFailed | Proxy sidecar restart failed. |
| ProxySidecarRestartPartiallySucceeded | Proxy sidecar restart partially succeeded. |
| ProxySidecarManualRestartRequired | A manual restart of the proxy sidecar is required for some workloads. |
| IngressGatewayRestartSucceeded | Istio ingress gateway restart succeeded. |
| IngressGatewayRestartFailed | Istio ingress gateway restart failed. |
| EgressGatewayRestartSucceeded | Istio egress gateway restart succeeded. |
| EgressGatewayRestartFailed | Istio egress gateway restart failed. |
| IngressTargetingUserResourceFound | Resource targeting Istio Ingress Gateway found. |
| IngressTargetingUserResourceNotFound | No resources targeting Istio Ingress Gateway found. |
| IngressTargetingUserResourceDetectionFailed | Resource targeting Istio Ingress Gateway detection failed. |
Configures the Istio installation.
Appears in:
| Field | Description | Validation |
|---|---|---|
| numTrustedProxies integer |
Defines the number of trusted proxies deployed in front of the Istio gateway proxy. | Maximum: 4.294967295e+09 Minimum: 0 |
| forwardClientCertDetails XFCCStrategy |
Defines the strategy of handling the X-Forwarded-Client-Cert header only by the gateway proxies. This setting controls how the gateway proxy retrieves client attributes from incoming traffic and propagates them to upstream services in the cluster. Gateway proxies in Istio module are represented by the Istio Ingress Gateway and Istio Egress Gateway. The default behavior for gateway proxies is "SANITIZE_SET". |
Enum: [APPEND_FORWARD SANITIZE_SET SANITIZE ALWAYS_FORWARD_ONLY FORWARD_ONLY] Optional |
| authorizers Authorizer array |
Defines a list of external authorization providers. | Optional |
| gatewayExternalTrafficPolicy string |
Defines the external traffic policy for the Istio Ingress Gateway Service. Valid configurations are "Local" or "Cluster". The external traffic policy set to "Local" preserves the client IP in the request, but also introduces the risk of unbalanced traffic distribution.WARNING: Switching externalTrafficPolicy may result in a temporal increase in request delay. Make sure that this is acceptable. |
Enum: [Local Cluster] Optional |
| telemetry Telemetry |
Defines the telemetry configuration of Istio. | Optional |
| trustDomain string |
Defines trust domain configuration of Istio. | MaxLength: 255 MinLength: 1 Optional Pattern: ^[a-z0-9]*([a-z0-9-_]*)?(\.[a-z0-9]*([a-z0-9-_]*[a-z0-9]*)?)*$ |
| enableDNSProxying boolean |
Enables or disables global DNS proxying in Istio sidecar and gateway proxies across the service mesh. When enabled, DNS requests from application Pods are intercepted by Istio proxies instead of being sent directly to upstream DNS servers. Enabling this setting allows Istio proxies to distinguish traffic between two different TCP services that are outside the mesh thanks to virtual IP address assignment to each ServiceEntry from reserved IP range 240.240.0.0/16. |
Optional |
Configures the Istio Egress Gateway component.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s KubernetesResourcesConfig |
Defines the Kubernetes resources' configuration for Istio Egress Gateway. It's a subset of KubernetesResourcesSpec. | Optional |
| enabled boolean |
Enables or disables Istio Egress Gateway. | Optional |
Defines experimental features.
Appears in:
| Field | Description | Validation |
|---|---|---|
| pilot PilotFeatures |
Defines experimental features for Istio Pilot. | Optional |
| enableAmbient boolean |
Enables ambient mode support. | Optional |
Configures the HorizontalPodAutoscaler.
Appears in:
| Field | Description | Validation |
|---|---|---|
| maxReplicas integer |
Defines the minimum number of replicas for the HorizontalPodAutoscaler. | Maximum: 2.147483647e+09 Minimum: 0 |
| minReplicas integer |
Defines the maximum number of replicas for the HorizontalPodAutoscaler. | Maximum: 2.147483647e+09 Minimum: 0 |
Specifies headers included, added, or forwarded during authorization. Exact, prefix, and suffix matches are supported, similar to the syntax used in AuthorizationPolicy rules (excluding the presence match):
- Exact match:
abcmatches the valueabc. - Prefix match:
abc*matches the valuesabcandabcd. - Suffix match:
*abcmatches the valuesabcandxabc.
Appears in:
| Field | Description | Validation |
|---|---|---|
| inCheck InCheck |
Defines the headers to be included or added in check authorization request. | Optional |
| toUpstream ToUpstream |
Defines the headers to be forwarded to the upstream (to the backend service). | Optional |
| toDownstream ToDownstream |
Defines the headers to be forwarded to the downstream (the client). | Optional |
Defines the headers to be included or added in check authorization request.
Appears in:
| Field | Description | Validation |
|---|---|---|
| include string array |
Lists client request headers included in the authorization request sent to the authorization service. In addition to the headers specified here, the following headers are included by default: - Host, Method, Path, and Content-Length are automatically sent. - Content-Length is set to 0, and the request doesn't have a message body. However, the authorization request can include the buffered client request body (controlled by the include_request_body_in_check setting), consequently the Content-Length value of the authorization request reflects its payload size. |
Optional |
| add object (keys:string, values:string) |
Specifies a set of additional fixed headers included in the authorization request sent to the authorization service. The key is the header name and value is the header value. Client request of the same key or headers specified in Include are overridden. |
Optional |
Contains the Istio custom resource's specification and its current status.
| Field | Description | Validation |
|---|---|---|
| apiVersion string |
operator.kyma-project.io/v1alpha2 |
Optional |
| kind string |
Istio |
Optional |
| metadata ObjectMeta |
For more information on the metadata fields, see Kubernetes API documentation. | Optional |
| spec IstioSpec |
Defines the desired state of the Istio installation. | Optional |
| status IstioStatus |
Defines the current state of the Istio installation. | Optional |
Defines the configuration for the generic Istio components, that is, Istio Ingress gateway and istiod.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s KubernetesResourcesConfig |
Defines the Kubernetes resources' configuration for Istio components. It's a subset of KubernetesResourcesSpec. | Required |
IstioSpec describes the desired specification for installing or updating Istio.
Appears in:
| Field | Description | Validation |
|---|---|---|
| config Config |
Configures the Istio installation. | Optional |
| components Components |
Configures Istio components. | Optional |
| experimental Experimental |
Defines experimental configuration options. | Optional |
| compatibilityMode boolean |
Enables the compatibility mode for the Istio installation. | Optional |
| networkPoliciesEnabled boolean |
Enables installation of network policies that are required for the module to work under a deny-all traffic policy in the kyma-system and istio-system namespaces.The default value is false, which means that the network policies aren't installed.This enforces a secure-by-default posture in the cluster. Enabling this option is likely to cause connectivity issues in the cluster if you don't properly set up your workloads first. |
Optional |
Defines the observed state of the Istio custom resource.
Appears in:
| Field | Description | Validation |
|---|---|---|
| state State |
Signifies the current state of the Istio custom resource. Possible values are Ready, Processing, Error, Deleting, or Warning. |
Enum: [Processing Deleting Ready Error Warning] Required |
| conditions Condition |
Contains conditions associated with IstioStatus. | Optional |
| description string |
Describes the Istio status. | Optional |
Defines Kubernetes-level configuration options for Istio components. It's a subset of KubernetesResourcesSpec.
Appears in:
| Field | Description | Validation |
|---|---|---|
| hpaSpec HPASpec |
Configures the HorizontalPodAutoscaler. | Optional |
| strategy Strategy |
Defines the rolling updates strategy. See Rolling Update Deployment. | Optional |
| resources Resources |
Defines Kubernetes resources' configuration. See Resource Management for Pods and Containers. | Optional |
Configures Istio telemetry metrics.
Appears in:
| Field | Description | Validation |
|---|---|---|
| prometheusMerge boolean |
Defines whether the prometheusMerge feature is enabled. If it is, appropriate prometheus.io annotations are added to all data plane Pods to set up scraping. If these annotations already exist, they are overwritten. With this option, the Envoy sidecar merges Istio’s metrics with the application metrics. The merged metrics are scraped from :15020/stats/prometheus. |
Optional |
Defines experimental features for Istio Pilot.
Appears in:
| Field | Description | Validation |
|---|---|---|
| enableAlphaGatewayAPI boolean |
Defines alpha Gateway API support. | Optional |
| enableMultiNetworkDiscoverGatewayAPI boolean |
Enables multi-network discovery for Gateway API. | Optional |
Configures the Istio sidecar proxy component.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s ProxyK8sConfig |
Contains a subset of KubernetesResourcesSpec. | Required |
Contains a subset of KubernetesResourcesSpec.
Appears in:
| Field | Description | Validation |
|---|---|---|
| resources Resources |
Defines Kubernetes resources' configuration. See Resource Management for Pods and Containers. | Optional |
Defines CPU and memory resource requirements for Kubernetes containers and Pods. See Resource Management for Pods and Containers.
Appears in:
| Field | Description | Validation |
|---|---|---|
| cpu string |
Specifies CPU resource allocation (requests or limits) | Pattern: ^([0-9]+m?|[0-9]\.[0-9]{1,3})$ |
| memory string |
Specifies memory resource allocation (requests or limits). | Pattern: ^[0-9]+(((\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki|m)?)|(e[0-9]+))$ |
Defines Kubernetes resources' configuration. See Resource Management for Pods and Containers.
Appears in:
| Field | Description | Validation |
|---|---|---|
| limits ResourceClaims |
The maximum amount of resources a container is allowed to use. | Optional |
| requests ResourceClaims |
The minimum amount of resources (such as CPU and memory) a container needs to run. | Optional |
Defines the configuration for rolling updates. See Rolling Update Deployment.
Appears in:
| Field | Description | Validation |
|---|---|---|
| maxSurge IntOrString |
Specifies the maximum number of Pods that can be created over the desired number of Pods. See Max Surge. | Optional Pattern: ^[0-9]+%?$ XIntOrString |
| maxUnavailable IntOrString |
Specifies the maximum number of Pods that can be unavailable during the update process. See Max Unavailable | Optional Pattern: ^((100|[0-9]{1,2})%|[0-9]+)$ XIntOrString |
Signifies the current state of the Istio custom resource.
The possible values are Ready, Processing, Error, Deleting, or Warning.
Underlying type: string
Appears in:
| Field | Description |
|---|---|
| Ready | Istio installation or upgrade process has completed successfully. |
| Processing | Istio installation or upgrade process is in progress. |
| Error | Istio installation or upgrade process has failed. |
| Deleting | The Istio custom resource is being deleted. |
| Warning | Istio installation or upgrade process has completed with warnings. This state warrants user attention, as some features may not work as expected. |
Defines the rolling updates strategy. See Rolling Update Deployment.
Appears in:
| Field | Description | Validation |
|---|---|---|
| rollingUpdate RollingUpdate |
Defines the configuration for rolling updates. See Rolling Update Deployment. | Required |
Configures Istio telemetry.
Appears in:
| Field | Description | Validation |
|---|---|---|
| metrics Metrics |
Configures Istio telemetry metrics. | Optional |
Defines the headers to be forwarded to the downstream (the client).
Appears in:
| Field | Description | Validation |
|---|---|---|
| onAllow string array |
Lists headers from the authorization service forwarded to downstream when the authorization check result is allowed (HTTP code 200).If not specified, the original request is forwarded to the backend unmodified. Any existing headers are overridden. |
Optional |
| onDeny string array |
Lists headers from the authorization service forwarded to downstream when the authorization check result is not allowed (HTTP code is other than 200).If not specified, all the authorization response headers, except Authority (Host), are included in the response to the downstream. When a header is included in this list, the following headers are automatically added: Path, Status, Content-Length, WWWAuthenticate, and Location. The body from the authorization service is always included in the response to downstream. |
Optional |
Defines the headers to be forwarded to the upstream (to the backend service).
Appears in:
| Field | Description | Validation |
|---|---|---|
| onAllow string array |
Lists headers from the authorization service added or overridden in the original request and forwarded to the upstream when the authorization check result is allowed (HTTP code 200).If not specified, the original request is forwarded to the backend unmodified. Any existing headers are overridden. |
Optional |
Defines how the proxy handles the X-Forwarded-Client-Cert (XFCC) of the HTTP header. XFCC is a proxy header that indicates certificate information of part or all of the clients or proxies that a request has passed through on its route from the client to the server.
Underlying type: string
Appears in:
| Field | Description |
|---|---|
| APPEND_FORWARD | When the client connection is mutual TLS (mTLS), append the client certificate information to the request’s XFCC header and forward it. This is the default value for sidecar proxies. |
| SANITIZE_SET | When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop. This is the default value for gateway proxies. |
| SANITIZE | Do not send the XFCC header to the next hop. |
| ALWAYS_FORWARD_ONLY | Always forward the XFCC header in the request, regardless of whether the client connection is mTLS. |
| FORWARD_ONLY | When the client connection is mTLS, forward the XFCC header in the request. |