.. _service:

Services
--------

When you create a deployment with multiple replicas, you have an address for each replica of a container.
A service consolidates all of that much like a load balancer into a single IP address.  In addition, these
pods may go up and down due to rolling updates and failure recovery.  The service provides a stable route
to available pods.

The service must specify a selector - a set of labels that identify the pods that will be
"load balanced" by the service.

Here is a sample YAML file describing a service::

    apiVersion: v1
    kind: Service
    metadata:
      name: tomcat-svc-dev
      labels:
            svc: tomcat
            env: dev
    spec:
      type: ClusterIP
      ports:
      - port: 8080
        targetPort: 8080
        protocol: TCP
      selector:
            app: tomcat
            env: dev

Note: It is important to understand that the **selector**, which is a list of name/value pairs, must
match the name/value pairs in the **label** of the deployments.  Here is a description of a matching deployment::


    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: tomcat-dev
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: tomcat
          env: dev
      strategy:
        type: RollingUpdate
        rollingUpdate:
          maxSurge: 1
          maxUnavailable: 1
      minReadySeconds: 5
      template:
        metadata:
          labels:                           # Labels assigned to the pod.  This is useful to find pods by label.
            app: tomcat
            env: dev
        spec:
          containers:
          - name: tomcat
            image: tomcat:7
            ports:
              - containerPort: 8080
            env:
              - name: DS_URL
                valueFrom:
                  secretKeyRef:
                    name: tomcat-dev
                    key: url
              - name: DS_USR
                valueFrom:
                  secretKeyRef:
                    name: tomcat-dev
                    key: username
              - name: DS_PWD
                valueFrom:
                  secretKeyRef:
                    name: tomcat-dev
                    key: password

Here is a sample of a deployment with services::

    from k9.core import (
        set_default_namespace,
        create_namespace,
        create_secret,
        create_deployment,
        create_service,
        read_yaml
    )

    # Create namespace
    set_default_namespace("service-unit-test")
    create_namespace()

    # Create secret - don't save passwords in source code
    # for real systems - this is just an example.  See
    # documentation on Secrets.
    secret_name = "tomcat-dev"
    secrets = {
        'url': 'https://some/url',
        'password': 'My1SecretPassword',
        'username': 'postgres'
    }
    create_secret(secret_name, secrets)

    # create deployment
    body = read_yaml('tomcat-deploy-dev.yml')
    create_deployment(body)

    # create service
    body = read_yaml('tomcat-svc-dev.yml')
    create_service(body)


.. autofunction:: k9.core.list_services
.. autofunction:: k9.core.service_exists
.. autofunction:: k9.core.get_service
.. autofunction:: k9.core.create_service
.. autofunction:: k9.core.delete_service