The service-with-healthchecks module: Custom Resources

ServiceWithHealthchecks

Short names: swh

Scope: Namespaced
Version: v1alpha1

• apiVersion

  string
• kind

  string
• metadata

  object
• spec

  object

  Defines the desired state of ServiceWithHealthchecks.

  For the ServiceWithHealthchecks load balancers you create to work, the following conditions must be met:

  • The network policy of the custom project in which the ServiceWithHealthchecks will be created must include a rule allowing incoming traffic from all pods in the d8-service-with-healthchecks namespace:

    ingress:
    - from:
      - namespaceSelector:
          matchLabels:
            kubernetes.io/metadata.name: d8-service-with-healthchecks

    For more information on network policies, see the Configuring Network Policies section.

  • The cluster role used in ClusterRoleBinding and RoleBinding when assigning permissions to users and service accounts for the ServiceWithHealthchecks resource must be extended with the following rules:

    • get
    • list
    • watch
    • create
    • update
    • patch
    • delete.

    For more details, see the section Granting permissions to users and service accounts.

  • spec.allocateLoadBalancerNodePorts

    boolean

    Determines whether NodePort should be automatically allocated for services of LoadBalancer type. Default is true. It may be set to false if the cluster load-balancer does not rely on NodePorts.

    If the caller requests specific NodePorts (by specifying a value), those requests will be respected, regardless of this field. This parameter can be set only for services of LoadBalancer type and is automatically reset when the type is changed to another.

  • spec.clusterIP

    string

    The IP address of the service.

    Normally, the IP address is randomly assigned to the service. If the IP address is manually specified, it must be within the valid range (specified by the system configuration) and free for assignment; otherwise, service creation will fail.

    This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above).

    Valid values are None, empty string (""), or a valid IP address. Setting this to None makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail.

    Warning. The field is immutable and is only honoured while the child Service is created. The address in use is reported in status.clusterIP. This field will be wiped when updating a Service to type ExternalName. More info.

  • spec.externalIPs

    array of strings

    A list of IP addresses where 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.

  • spec.externalName

    string

    An external reference that discovery mechanisms will return as an alias for this service (e.g., a DNS record CNAME).

    Must be a lowercase RFC-1123 hostname and requires type to be “ExternalName”.

  • spec.externalTrafficPolicy

    string

    Describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to Local, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. Traffic mistakenly sent to a node with no endpoints will be dropped.

    The default value, Cluster, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features).

    Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get Cluster semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node.

  • spec.healthCheckNodePort

    integer

    Specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used.

    If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not.

    If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type).

    Warning. The field is immutable and is only honoured while the child Service is created.

  • spec.healthcheck

    object
    • spec.healthcheck.initialDelaySeconds

      integer

      Number of seconds after the container has started before liveness probes are initiated.

      Default: 10

      Allowed values: 0 <= X <= 108000

    • spec.healthcheck.periodSeconds

      integer

      How often (in seconds) to perform the probe.

      Default: 10

      Allowed values: 1 <= X <= 108000

    • spec.healthcheck.probes

      array of objects
      • spec.healthcheck.probes.failureThreshold

        integer

        Minimum consecutive failures for the probe to be considered failed after having succeeded.

        Default: 3

        Allowed values: 1 <= X

      • spec.healthcheck.probes.http

        object
        • spec.healthcheck.probes.http.caCert

          string

          CA certificate for HTTPS connection.
        • spec.healthcheck.probes.http.code

          array of integers

          Response status codes that are treated as a successful probe.

          If omitted, any code in the 200-399 range is considered successful.

          • spec.healthcheck.probes.http.code.Element of the array

            integer

            Allowed values: 200 <= X <= 399

        • spec.healthcheck.probes.http.host

          string

          Hostname to connect to, defaults to the pod’s IP address.
        • spec.healthcheck.probes.http.httpHeaders

          array of objects

          Custom headers that will be added to the HTTP request and used when performing the probe. Duplicate headers are allowed.
          • spec.healthcheck.probes.http.httpHeaders.name

            string

            The header name.

            This will be canonicalized upon output, so case-variant names will be understood as the same header.

          • spec.healthcheck.probes.http.httpHeaders.value

            string

            The header value.
        • spec.healthcheck.probes.http.insecureSkipTLSVerify

          boolean

          Indicates if the client should skip verifying the server’s TLS certificate chain and hostname.

          Default: false

        • spec.healthcheck.probes.http.method

          string

          Method to use for the request.

          Default: GET

          Allowed values: GET, HEAD

        • spec.healthcheck.probes.http.path

          string

          Path to access on the HTTP server.

          Must start with / and must not contain CR or LF characters.

          Pattern: ^/[^\r\n]*$

        • spec.healthcheck.probes.http.scheme

          string

          Scheme to use for connecting to the host.

          Default: HTTP

          Allowed values: HTTP, HTTPS

        • spec.healthcheck.probes.http.targetPort

          integer

          Required value

          Number of the port to access on the container.

          Allowed values: 1 <= X <= 65535

      • spec.healthcheck.probes.mode

        string

        The mode for the probe.

        Allowed values: HTTP, TCP, PostgreSQL

      • spec.healthcheck.probes.postgreSQL

        object
        • spec.healthcheck.probes.postgreSQL.authSecretName

          string

          The name of the secret located in the same namespace as this resource.

          The secret can contain the following authentication fields: tlsMode, clientCert, clientKey, caCert, password, user.

          Warning. The type of the secret must be network.deckhouse.io/postgresql-credentials.

        • spec.healthcheck.probes.postgreSQL.dbName

          string

          Optional Database Name.
        • spec.healthcheck.probes.postgreSQL.query

          string

          Query to PostgreSQL for testing.

          Must return one of the values TRUE: t, true, y, yes,1. to be considered successful.

          Warning. The privileges for the user under whom the requests are executed should be minimal.

          Default: select 1

        • spec.healthcheck.probes.postgreSQL.targetPort

          integer

          Required value

          Number of the port to access on the container.

          Allowed values: 1 <= X <= 65535

      • spec.healthcheck.probes.successThreshold

        integer

        Minimum consecutive successes for the probe to be considered successful after having failed.

        Default: 1

        Allowed values: 1 <= X

      • spec.healthcheck.probes.tcp

        object
        • spec.healthcheck.probes.tcp.targetPort

          integer

          Required value

          Number of the port to access on the container.

          Allowed values: 1 <= X <= 65535

      • spec.healthcheck.probes.timeoutSeconds

        integer

        Number of seconds after which the probe times out.

        Default: 1

        Allowed values: 1 <= X

  • spec.internalTrafficPolicy

    string

    Describes how nodes distribute service traffic they receive on the ClusterIP.

    If set to Local, the proxy will assume that pods only want to talk to endpoints of the service on the same node as the pod, dropping the traffic if there are no local endpoints.

    The default value, Cluster, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features).

    Default: Cluster

  • spec.ipFamilies

    array of strings

    A family of IP addresses (e.g., IPv4, IPv6) assigned to a service. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field.

    If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service.

    Valid values are IPv4 and IPv6.This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to “headless” services.

    This field will be wiped when updating a Service to type ExternalName.

    This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field.

    • spec.ipFamilies.Element of the array

      string

      Represents the IP Family (IPv4 or IPv6).

      This type is used to express the family of an IP expressed by a type (e.g. service.spec.ipFamilies).

  • spec.ipFamilyPolicy

    string

    Required or requested dual stack support for the service.

    If there is no value provided, then this field will be set to SingleStack. Services can be SingleStack (a single IP family), PreferDualStack (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or RequireDualStack (two IP families on dual-stack configured clusters, otherwise fail).

    The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName.

  • spec.loadBalancerClass

    string

    The class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. internal-vip or example.com/internal-vip. Unprefixed names are reserved for end-users.

    This field can only be set when the Service type is LoadBalancer.

    If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation.

    If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field.

    Warning. The field is immutable. To use another load balancer implementation, recreate the resource.

    Once set, it can not be changed. This field will be wiped when a service is updated to a non LoadBalancer type.

  • spec.loadBalancerIP

    string

    The address to request for the load balancer. Only applies to type: LoadBalancer.

    Warning. The field is deprecated in Kubernetes. An implementation may ignore it and assign a different address, or none. Prefer the annotation the implementation offers instead: annotations of this resource are copied to the child Service.

  • spec.loadBalancerSourceRanges

    array of strings

    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.

  • spec.ports

    array of objects

    The list of ports that are exposed by this service. More info.
    • spec.ports.appProtocol

      string

      The application protocol for this port. This is used as a hint for implementations to offer richer behavior for protocols that they understand. This field follows standard Kubernetes label syntax. Valid values are either:

      • Un-prefixed protocol names - reserved for IANA standard service names as RFC-6335.
      • Kubernetes-defined prefixed names:
        • kubernetes.io/h2c — HTTP/2 prior knowledge over cleartext as described in RFC;
        • kubernetes.io/ws — WebSocket over cleartext as described in RFC;
        • kubernetes.io/wss — WebSocket over TLS as described in RFC.
      • Other protocols should use implementation-defined prefixed names such as mycompany.com/my-custom-protocol.
    • spec.ports.name

      string

      The name of this port within the service. Must be a DNS_LABEL.

      Port names must be unique within the service: a consumer resolving the service matches this name against the name of the published endpoint port.

      May be omitted if the service defines a single port. With more than one port, every port must be named.

      Maximum length: 63

      Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

    • spec.ports.nodePort

      integer

      The port on each node on which this service is exposed when type is NodePort or LoadBalancer. Usually assigned by the system. If a value is specified, in-range, and not in use it will be used, otherwise the operation will fail.

      If not specified, a port will be allocated if this Service requires one.

      If this field is specified when creating a Service which does not need it, creation will fail.

      This field will be wiped when updating a Service to no longer need it (e.g. changing type from NodePort to ClusterIP). More info.

    • spec.ports.port

      integer

      The port that will be exposed by this service.
    • spec.ports.protocol

      string

      The IP protocol for this port. Supports TCP, UDP, and SCTP.

      Default: TCP

    • spec.ports.targetPort

      integer

      Number of the port to access on the pods targeted by the service.

      If this is not specified, the value of the port field is used (an identity map).

      This field is ignored for services with clusterIP=None, and should be omitted or set equal to the port field. More info.

  • spec.publishNotReadyAddresses

    boolean

    Indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet’s Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery.

    The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered “ready” even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior.

  • spec.selector

    object

    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.

  • spec.sessionAffinity

    string

    Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. More info.
  • spec.sessionAffinityConfig

    object

    Contains the configurations of session affinity.
    • spec.sessionAffinityConfig.clientIP

      object

      Contains the configurations of ClientIP based session affinity.
      • spec.sessionAffinityConfig.clientIP.timeoutSeconds

        integer

        Specifies the seconds of ClientIP type session sticky time. The value must be >0 && <=86400 (for 1 day) if ServiceAffinity == ClientIP.
  • spec.trafficDistribution

    string

    Offers a way to express preferences for how traffic is distributed to Service endpoints. Implementations can use this field as a hint, but are not required to guarantee strict adherence.

    If the field is not set, the implementation will apply its default routing strategy. If set to PreferClose, implementations should prioritize endpoints that are topologically close (e.g., same zone).

  • spec.type

    string

    Determines how the Service is exposed.

    Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer.

    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 or EndpointSlice objects.

    If clusterIP is None, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP.

    NodePort builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP.

    LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

    ExternalName aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info.

    Default: ClusterIP

• status

  object

  Defines the observed state of ServiceWithHealthchecks
  • status.clusterIP

    string

    The address of the child Service: the one requested in spec.clusterIP, or the one the cluster allocated.
  • status.clusterIPs

    array of strings

    All the addresses of the child Service, one per IP family.
  • status.conditions

    array of objects

    Current service state:

    • ChildServiceReady — whether the child Service could be created and belongs to this resource.
    • LoadBalancerReady — for type: LoadBalancer only, whether an address has been assigned.
    • Ready — whether every published endpoint passes its probes.
    • status.conditions.lastTransitionTime

      string

      Is the last time the condition transitioned from one status to another. This should be when the underlying condition changed.

      If that is not known, then using the time when the API field changed is acceptable.

    • status.conditions.message

      string

      Is a human readable message indicating details about the transition.

      This may be an empty string.

      Maximum length: 32768

    • status.conditions.observedGeneration

      integer

      Represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

      Allowed values: 0 <= X

    • status.conditions.reason

      string

      Contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API.

      The value should be a CamelCase string.

      This field may not be empty.

      Length: 1..1024

      Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

    • status.conditions.status

      string

      status of the condition, one of True, False, Unknown.

      Allowed values: True, False, Unknown

    • status.conditions.type

      string

      Condition in CamelCase or in foo.example.com/CamelCase.

      Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt).

      Maximum length: 316

      Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$

  • status.endpointStatuses

    array of objects

    Current service state.
    • status.endpointStatuses.failedProbes

      array of strings

      List of probes that are currently in the failed state.

      A probe appears here once it has crossed its failureThreshold, and disappears once it has crossed its successThreshold again. This is exactly the set of probes that keeps probesSuccessful false.

    • status.endpointStatuses.lastProbeTime

      string

      The time when the pod was last probed (updated based on verboseStatus configuration).
    • status.endpointStatuses.lastTransitionTime

      string

      The time when the probe state last transitioned from one status to another.
    • status.endpointStatuses.nodeName

      string

      The node where the pod is running.
    • status.endpointStatuses.podName

      string

      The name of the pod being checked.
    • status.endpointStatuses.probesSuccessful

      boolean

      Indicates whether all custom ServiceWithHealthchecks probes were successful.
    • status.endpointStatuses.ready

      boolean

      Indicates whether the endpoint is ready, meaning the pod passed the standard Kubernetes readiness probes and all custom ServiceWithHealthchecks probes succeeded.

      Endpoints counted in readyEndpoints are the ones marked ready here. When this is false while probesSuccessful is true, it is the pod itself that is not ready.

  • status.healthcheckCondition

    object

    Summary of health checks.
    • status.healthcheckCondition.endpoints

      integer

      Total number of endpoints targeted by the health checks.
    • status.healthcheckCondition.observedGeneration

      integer

      The most recent generation observed by the controller.
    • status.healthcheckCondition.readyEndpoints

      integer

      Number of endpoints that successfully passed the health checks.
  • status.loadBalancer

    object

    Contains the current status of the load-balancer, if one is present.
    • status.loadBalancer.ingress

      array of objects

      Is a list containing ingress points for the load-balancer. Traffic intended for the service should be sent to these ingress points.
      • status.loadBalancer.ingress.hostname

        string

        Is set for load-balancer ingress points that are DNS based (typically AWS load-balancers)
      • status.loadBalancer.ingress.ip

        string

        Is set for load-balancer ingress points that are IP based (typically GCE or OpenStack load-balancers)
      • status.loadBalancer.ingress.ipMode

        string

        Specifies how the load-balancer IP behaves, and may only be specified when the ip field is specified. Setting this to VIP indicates that traffic is delivered to the node with the destination set to the load-balancer’s IP and port.

        Setting this to Proxy indicates that traffic is delivered to the node or pod with the destination set to the node’s IP and node port or the pod’s IP and port.

        Service implementations may use this information to adjust traffic routing.

      • status.loadBalancer.ingress.ports

        array of objects

        Is a list of records of service ports

        If used, every port defined in the service should have an entry in it

        • status.loadBalancer.ingress.ports.error

          string

          The problem the load balancer reported for this port, in the wording of its implementation.

          Maximum length: 316

        • status.loadBalancer.ingress.ports.port

          integer

          Is the port number of the service port of which status is recorded here
        • status.loadBalancer.ingress.ports.protocol

          string

          Is the protocol of the service port of which status is recorded here

          The supported values are: TCP, UDP, SCTP

          Default: TCP

  • status.ports

    string

    The ports of the child Service, for example 80/TCP,443:31443/TCP.