Istio Custom Resource ​
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:
shell
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.
Custom Resource Parameters ​
This table lists all the possible parameters of Istio CR together with their descriptions:
Spec ​
| Parameter | Type | Description |
|---|---|---|
| compatibilityMode | bool | Enables compatibility mode in Istio. See Compatibility Mode. If a specific compatibility version introduces new flags to the Istio proxy component, enabling the compatibility mode causes a restart of Istio sidecar proxies. |
| components.cni | object | Defines component configuration for Istio CNI DaemonSet. |
| components.cni.k8s.affinity | object | Affinity is a group of affinity scheduling rules. To learn more, read about affininty in the Istio documentation. |
| components.cni.k8s.resources | object | Defines Kubernetes resources requests and limits configuration. For more information, read about Resources in the Istio documentation. |
| components.ingressGateway | object | Defines component configurations for Istio Ingress Gateway. |
| components.ingressGateway.k8s.hpaSpec | object | Defines configuration for HorizontalPodAutoscaler. |
| components.ingressGateway.k8s.hpaSpec.maxReplicas | integer | Specifies the upper limit for the number of Pods that can be set by the autoscaler. It cannot be smaller than MinReplicas. |
| components.ingressGateway.k8s.hpaSpec.minReplicas | integer | Specifies the lower limit for the number of replicas to which the autoscaler can scale down. By default, it is set to 1 Pod. The value can be set to 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available. |
| components.ingressGateway.k8s.resources | object | Defines Kubernetes resources requests and limits configuration. To learn more, read the Istio documentation. |
| components.ingressGateway.k8s.strategy | object | Defines the rolling update strategy. To learn more, read about DeploymentStrategy in the Istio documentation. |
| components.egressGateway | object | Defines component configurations for Istio Egress Gateway. |
| components.egressGateway.enabled | bool | Enables Istio Egress Gateway. |
| components.egressGateway.k8s.hpaSpec | object | Defines configuration for HorizontalPodAutoscaler. |
| components.egressGateway.k8s.hpaSpec.maxReplicas | integer | Specifies the upper limit for the number of Pods that can be set by the autoscaler. It cannot be smaller than MinReplicas. |
| components.egressGateway.k8s.hpaSpec.minReplicas | integer | Specifies the lower limit for the number of replicas to which the autoscaler can scale down. By default, it is set to 1 Pod. The value can be set to 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available. |
| components.egressGateway.k8s.resources | object | Defines Kubernetes resources requests and limits configuration. To learn more, read the Istio documentation. |
| components.egressGateway.k8s.strategy | object | Defines the rolling update strategy. To learn more, read about DeploymentStrategy in the Istio documentation. |
| components.pilot | object | Defines component configuration for Istiod. |
| components.pilot.k8s.hpaSpec | object | Defines configuration for HorizontalPodAutoscaler. |
| components.pilot.k8s.hpaSpec.maxReplicas | integer | Specifies the upper limit for the number of Pods that can be set by the autoscaler. It cannot be smaller than MinReplicas. |
| components.pilot.k8s.hpaSpec.minReplicas | integer | Specifies the lower limit for the number of replicas to which the autoscaler can scale down. By default, it is set to 1 Pod. The value can be set to 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available. |
| components.pilot.k8s.resources | object | Defines Kubernetes resources requests and limits configuration. For more information, read about Resources in the Istio documentation. |
| components.pilot.k8s.strategy | object | Defines the rolling update strategy. To learn more, read about DeploymentStrategy in the Istio documentation. |
| components.proxy | object | Defines component configuration for the Istio proxy sidecar. |
| components.proxy.k8s.resources | object | Defines Kubernetes resources requests and limits configuration. To learn more, read about Resources in the Istio documnetation. |
| config | object | Specifies the configuration for the Istio installation. |
| config.authorizers | []authorizer | Specifies the list of external authorizers configured in the Istio service mesh config. |
| config.numTrustedProxies | integer | Specifies the number of trusted proxies deployed in front of the Istio gateway proxy. Updating the field causes a restart of the Istio proxies that are part of the istio-ingressgateway Deployment. |
| config.gatewayExternalTrafficPolicy | string | Defines the external traffic policy for 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. |
| config.telemetry.metrics.prometheusMerge | bool | Enables the prometheusMerge feature from Istio, which merges the application's and Istio's metrics and exposes them together at :15020/stats/prometheus for scraping using plain HTTP. Updating the field causes a restart of the Istio sidecar proxies. |
| experimental | object | Defines additional experimental features that can be enabled in experimental builds. |
| experimental.pilot | object | Defines additional experimental features that can be enabled in Istio pilot component. |
| experimental.pilot.enableAlphaGatewayAPI | bool | Enables support for alpha Kubernetes Gateway API. |
| experimental.pilot.enableMultiNetworkDiscoverGatewayAPI | bool | Enables support for multi-network discovery in Kubernetes Gateway API. |
Authorizer ​
| Parameter | Type | Description |
|---|---|---|
| name (required) | string | A unique name identifying the extension authorization provider. |
| service (required) | string | Specifies the service that implements the Envoy ext_authz HTTP authorization service. The recommended format is [<Namespace>/]<Hostname>. |
| port (required) | integer | Specifies the port number of the external authorizer used to make the authorization request. |
| headers | headers | Specifies headers to be included, added, or forwarded during authorization. |
Headers ​
| Parameter | Type | Description |
|---|---|---|
| inCheck | object | Defines headers to be included or added in the authorization request check. |
| inCheck.include | []string | Specifies a list of client request headers that should be included in the authorization request sent to the authorization service. |
| inCheck.add | key-value | Defines a set of additional fixed headers that should be included in the authorization request sent to the authorization service. The key is the header's name, and the value is the header's value. It overrides a client request of the same key or headers specified in the include field. |
| toUpstream | object | Defines headers to be forwarded to the upstream. |
| toUpstream.onAllow | []string | Specifies a list of headers from the authorization service that should be 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 will not be modified and forwarded to the backend as-is. It overrides any existing headers. |
| toDownstream | object | Defines headers to be forwarded to the downstream. |
| toDownstream.onAllow | []string | Specifies a list of headers from the authorization service that should be added or overridden in the original request and forwarded to the downstream when the authorization check result is allowed (HTTP code 200). If not specified, the original request will not be modified and forwarded to backend as-is. It overrides any existing headers. |
| toDownstream.onDeny | []string | List of headers from the authorization service that should be forwarded to downstream when the authorization check result is not allowed (HTTP code other than 200). If not specified, the response to the downstream will contain all the authorization response headers, except Authority (Host). When a header is included in this list, Path, Status, Content-Length, WWWAuthenticate, and Location are automatically added. Note that the body from the authorization service is always included in the response to downstream. |
Status ​
| Parameter | Type | Description |
|---|---|---|
| state (required) | string | Signifies the current state of the CR. Its value can be either Ready, Processing, Error, Warning, or Deleting. |
| conditions | []object | Represents the current state of the CR's conditions. |
| conditions.​lastTransitionTime | string | Defines the date of the last condition status change. |
| conditions.​message | string | Provides more details about the condition status change. |
| conditions.​reason | string | Defines the reason for the condition status change. |
| conditions.​status (required) | string | Represents the status of the condition. The value is either True, False, or Unknown. |
| conditions.​type | string | Provides a short description of the condition. |
Istio CR's State ​
See the possible values of the status.state field:
| Code | Description |
|---|---|
Ready | Istio Controller finished reconciliation. |
Processing | Istio Controller is installing or upgrading Istio. |
Deleting | Istio Controller is uninstalling Istio. |
Error | An error occurred during reconciliation. |
Warning | Istio Controller is misconfigured. |
Istio CR's Status Conditions ​
See the possible values of the status.conditions fields:
| Istio CR's State | Type | Status | Reason | Message |
|---|---|---|---|---|
Ready | Ready | True | ReconcileSucceeded | Reconciliation succeeded. |
Error | Ready | False | ReconcileFailed | Reconciliation failed. |
Warning | Ready | False | OlderCRExists | This Istio custom resource is not the oldest one and does not represent the module state. |
Processing | Ready | False | IstioInstallNotNeeded | Istio installation is not needed. |
Processing | Ready | False | IstioInstallSucceeded | Istio installation succeeded. |
Processing | Ready | False | IstioUninstallSucceeded | Istio uninstallation succeeded. |
Error | Ready | False | IstioInstallUninstallFailed | Istio install or uninstall failed. |
Error | Ready | False | IstioCustomResourceMisconfigured | Istio custom resource has invalid configuration. |
Warning | Ready | False | IstioCustomResourcesDangling | Istio deletion blocked because of existing Istio custom resources. |
Processing | Ready | False | CustomResourcesReconcileSucceeded | Custom resources reconciliation succeeded. |
Error | Ready | False | CustomResourcesReconcileFailed | Custom resources reconciliation failed. |
Processing | ProxySidecarRestartSucceeded | True | ProxySidecarRestartSucceeded | Proxy sidecar restart succeeded. |
Error | ProxySidecarRestartSucceeded | False | ProxySidecarRestartFailed | Proxy sidecar restart failed. |
Processing | ProxySidecarRestartSucceeded | False | ProxySidecarPartiallySucceeded | Proxy sidecar restart partially succeeded. |
Warning | ProxySidecarRestartSucceeded | False | ProxySidecarManualRestartRequired | Proxy sidecar manual restart is required for some workloads. |
Processing | Ready | False | IngressGatewayReconcileSucceeded | Istio Ingress Gateway reconciliation succeeded. |
Error | Ready | False | IngressGatewayReconcileFailed | Istio Ingress Gateway reconciliation failed. |
Processing | Ready | False | EgressGatewayReconcileSucceeded | Istio Egress Gateway reconciliation succeeded. |
Error | Ready | False | EgressGatewayReconcileFailed | Istio Egress Gateway reconciliation failed. |
Warning | Ready | False | IstioVersionUpdateNotAllowed | Update to the new Istio version is not allowed. |
Warning | IngressTargetingUserResourceFound | True | IngressTargetingUserResourceFound | Resource targeting Istio Ingress Gateway found. |
Ready | IngressTargetingUserResourceFound | False | IngressTargetingUserResourceFound | Resources targeting Istio Ingress Gateway not found. (default state) |
Warning | IngressTargetingUserResourceFound | Unknown | IngressTargetingUserResourceDetectionFailed | Resource targeting Istio Ingress Gateway detection failed. |