IstioControlPlane is a schema for both defining and customizing Istio control plane installations.
Running the operator with an empty user defined InstallSpec results in an control plane with default values, using the
default charts.
The simplest install specialization is to point the user InstallSpec profile to a different values file, for
example an Istio minimal control plane, which will use the values associated with the minimal control plane profile for
Istio.
Deeper customization is possible at three levels:
New APIs defined in this file
Feature API: this API groups an Istio install by features and allows enabling/disabling the features, selecting base
control plane profiles, as well as some additional high level settings that are feature specific. Each feature contains
one or more components, which correspond to Istio components (Pods) in the cluster.
k8s API: this API is a pass through to k8s resource settings for Istio k8s resources. It allows customizing Istio k8s
resources like Affinity, Resource requests/limits, PodDisruptionBudgetSpec, Selectors etc. in a more consistent and
k8s specific way compared to values.yaml. See KubernetesResourcesSpec in this file for details.
values.yaml
The entirety of values.yaml settings is accessible through InstallSpec (see CommonComponentSpec/Values).
This API will gradually be deprecated and values there will be moved either into CRDs that are used to directly
configure components or, in the case of k8s settings, will be replaced by the new API above.
k8s resource overlays
Once a manifest is rendered from InstallSpec, a further customization can be applied by specifying k8s resource
overlays. The concept is similar to kustomize, where JSON patches are applied for object paths. This allows
customization at the lowest level and eliminates the need to create ad-hoc template parameters, or edit templates.
Here are a few example uses:
Default Istio install
spec:
Default minimal profile install
spec:
profile: minimal
Default install with telemetry disabled
spec:
telemetry:
enabled: false
Default install with each feature installed to different namespace and security components in separate namespaces
IstioControlPlaneSpec defines the desired state of IstioControlPlane.
The spec is a used to define a customization of the default profile values that are supplied with each Istio release.
It is grouped at the top level by feature, where behavior of Istio functional areas is specified.
Each feature contains components, where k8s resource level defaults can be overridden.
Because the spec is a customization API, specifying an empty InstallSpec results in a default Istio control plane.
Field
Type
Description
Required
defaultNamespace
string
Default namespace if feature or component namespaces are not set.
Unvalidated overrides for default global values.yaml.
No
profile
string
Path or name for the profile e.g.
- minimal (looks in profiles dir for a file called minimal.yaml)
- /tmp/istio/install/values/custom/custom-install.yaml (local file path)
default profile is used if this field is unset.
No
installPackagePath
string
Path for the install package. e.g.
- /tmp/istio-installer/nightly (local file path)
No
hub
string
Root for docker image paths e.g. docker.io/istio-release.
Releases are published to docker hub under ‘istio’ project.
Daily builds from prow are on gcr.io, and nightly builds from circle on docker.io/istionightly
No
tag
string
Version tag for docker images e.g. 1.0.6
No
KubernetesResourcesSpec
KubernetesResourcesConfig is a common set of k8s resource configs for components.
k8s pod annotations.
https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/
No
priorityClassName
string
k8s priorityclassname. Default for all resources unless overridden.
https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass
scaleTargetRef points to the target resource to scale, and is used to the pods for which metrics
should be collected, as well as to actually change the replica count.
No
minReplicas
int32
minReplicas is the lower limit for the number of replicas to which the autoscaler
can scale down. It defaults to 1 pod. minReplicas is allowed to be 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.
+optional
No
maxReplicas
int32
maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up.
It cannot be less that minReplicas.
metrics contains the specifications for which to use to calculate the
desired replica count (the maximum replica count across all metrics will
be used). The desired replica count is calculated multiplying the
ratio between the target value and the current value by the current
number of pods. Ergo, metrics used must decrease as the pod count is
increased, and vice-versa. See the individual metric source types for
more information about how each type of metric must respond.
+optional
Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)).
+optional
No
k8s.io.api.core.v1.EnvVar
EnvVar represents an environment variable present in a Container.
Field
Type
Description
Required
name
string
Name of the environment variable. Must be a C_IDENTIFIER.
No
value
string
Variable references $(VARNAME) are expanded
using the previous defined environment variables in the container and
any service environment variables. If a variable cannot be resolved,
the reference in the input string will be unchanged. The $(VARNAME)
syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped
references will never be expanded, regardless of whether the variable
exists or not.
Defaults to “”.
+optional
The list of ports that are exposed by this service.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
+patchMergeKey=port
+patchStrategy=merge
+listType=map
+listMapKey=port
+listMapKey=protocol
No
selector
map<string, string>
Route service traffic to pods with label keys and values matching this
selector. If empty or not present, the service is assumed to have an
external process managing its endpoints, which Kubernetes will not
modify. Only applies to types ClusterIP, NodePort, and LoadBalancer.
Ignored if type is ExternalName.
More info: https://kubernetes.io/docs/concepts/services-networking/service/
+optional
No
clusterIP
string
clusterIP is the IP address of the service and is usually assigned
randomly by the master. If an address is specified manually and is not in
use by others, it will be allocated to the service; otherwise, creation
of the service will fail. This field can not be changed through updates.
Valid values are “None”, empty string (“”), or a valid IP address. “None”
can be specified for headless services when proxying is not required.
Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if
type is ExternalName.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
+optional
No
type
string
type determines how the Service is exposed. Defaults to ClusterIP. Valid
options are ExternalName, ClusterIP, NodePort, and LoadBalancer.
“ExternalName” maps to the specified externalName.
“ClusterIP” allocates a cluster-internal IP address for load-balancing to
endpoints. Endpoints are determined by the selector or if that is not
specified, by manual construction of an Endpoints object. If clusterIP is
“None”, no virtual IP is allocated and the endpoints are published as a
set of endpoints rather than a stable IP.
“NodePort” builds on ClusterIP and allocates a port on every node which
routes to the clusterIP.
“LoadBalancer” builds on NodePort and creates an
external load-balancer (if supported in the current cloud) which routes
to the clusterIP.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types
+optional
No
externalIPs
string[]
externalIPs is a list of IP addresses for which nodes in the cluster
will also accept traffic for this service. These IPs are not managed by
Kubernetes. The user is responsible for ensuring that traffic arrives
at a node with this IP. A common example is external load-balancers
that are not part of the Kubernetes system.
+optional
No
sessionAffinity
string
Supports “ClientIP” and “None”. Used to maintain session affinity.
Enable client IP based session affinity.
Must be ClientIP or None.
Defaults to None.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
+optional
No
loadBalancerIP
string
Only applies to Service Type: LoadBalancer
LoadBalancer will get created with the IP specified in this field.
This feature depends on whether the underlying cloud-provider supports specifying
the loadBalancerIP when a load balancer is created.
This field will be ignored if the cloud-provider does not support the feature.
+optional
No
loadBalancerSourceRanges
string[]
If specified and supported by the platform, this will restrict traffic through the cloud-provider
load-balancer will be restricted to the specified client IPs. This field will be ignored if the
cloud-provider does not support the feature.”
More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
+optional
No
externalName
string
externalName is the external reference that kubedns or equivalent will
return as a CNAME record for this service. No proxying will be involved.
Must be a valid RFC-1123 hostname (https://tools.ietf.org/html/rfc1123)
and requires Type to be ExternalName.
+optional
No
externalTrafficPolicy
string
externalTrafficPolicy denotes if this Service desires to route external
traffic to node-local or cluster-wide endpoints. “Local” preserves the
client source IP and avoids a second hop for LoadBalancer and Nodeport
type services, but risks potentially imbalanced traffic spreading.
“Cluster” obscures the client source IP and may cause a second hop to
another node, but should have good overall load-spreading.
+optional
No
healthCheckNodePort
int32
healthCheckNodePort specifies the healthcheck nodePort for the service.
If not specified, HealthCheckNodePort is created by the service api
backend with the allocated nodePort. Will use user-specified nodePort value
if specified by the client. Only effects when Type is set to LoadBalancer
and ExternalTrafficPolicy is set to Local.
+optional
No
publishNotReadyAddresses
bool
publishNotReadyAddresses, when set to true, indicates that DNS implementations
must publish the notReadyAddresses of subsets for the Endpoints associated with
the Service. The default value is false.
The primary use case for setting this field is to use a StatefulSet’s Headless Service
to propagate SRV records for its Pods without respect to their readiness for purpose
of peer discovery.
+optional
sessionAffinityConfig contains the configurations of session affinity.
+optional
No
ipFamily
string
ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs.
IPv6). If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is
available in the cluster. If no IP family is requested, the cluster’s primary IP family will be used.
Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which
allocate external load-balancers should use the same IP family. Endpoints for this Service will be of
this family. This field is immutable after creation. Assigning a ServiceIPFamily not available in the
cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment.
+optional
No
k8s.io.api.core.v1.Toleration
The pod this Toleration is attached to tolerates any taint that matches
the triple <key,value,effect> using the matching operator <operator>.
Field
Type
Description
Required
key
string
Key is the taint key that the toleration applies to. Empty means match all taint keys.
If the key is empty, operator must be Exists; this combination means to match all values and all keys.
+optional
No
operator
string
Operator represents a key’s relationship to the value.
Valid operators are Exists and Equal. Defaults to Equal.
Exists is equivalent to wildcard for value, so that a pod can
tolerate all taints of a particular category.
+optional
No
value
string
Value is the taint value the toleration matches to.
If the operator is Exists, the value should be empty, otherwise just a regular string.
+optional
No
effect
string
Effect indicates the taint effect to match. Empty means match all taint effects.
When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.
+optional
No
tolerationSeconds
int64
TolerationSeconds represents the period of time the toleration (which must be
of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
it is not set, which means tolerate the taint forever (do not evict). Zero and
negative values will be treated as 0 (evict immediately) by the system.
+optional
A label selector is a label query over a set of resources. The result of matchLabels and
matchExpressions are ANDed. An empty label selector matches all objects. A null
label selector matches no objects.
Field
Type
Description
Required
matchLabels
map<string, string>
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is “key”, the
operator is “In”, and the values array contains only “value”. The requirements are ANDed.
+optional
Path of the form a.b:c.e.:f
Where b:c is a list element selector of the form key:value and :f is a list selector of the form :value.
All path intermediate nodes must exist.
Value to add, delete or replace.
For add, the path should be a new leaf.
For delete, value should be unset.
For replace, path should reference an existing node.
All values are strings but are converted into appropriate type based on schema.