The shipa.yaml is a special file located at the root of the application source code. The name of the file may be either shipa.yaml or shipa.yml.

The file is used to describe certain aspects of the application being deployed. The file describes information about deployment hooks and deployment time health checks.

Deployment Hooks

Shipa provides different deployment hooks options, such as restart:before, restart:after and build. Deployment hooks allow developers to run commands during different stages of the application deployment.

Below is an example of how to declare hooks in the shipa.yaml file:

hooks:
  restart:
    before:
      - python manage.py local_file
    after:
      - python manage.py clear_cache

Currently, Shipa supports the following hooks:

• restart:before: executes commands before the unit is restarted. Commands listed in this hook run once per unit. For instance, if there is an application with two units and the shipa.yaml file listed above, the command python manage.py local_file would run two times, once per unit.
• restart:after: works like before-each, but runs after restarting a unit.

Healthcheck

Developers can declare a health check in the shipa.yaml file. Provide health check probes as defined at https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/ under healthcheck element as described below:

healthcheck:
    readinessProbe:
        exec:
            command:
                - cat
                - /tmp/healthy
        initialDelaySeconds: 5
        periodSeconds: 5
    livenessProbe:
        exec:
            command:
                - cat
                - /tmp/lively
        initialDelaySeconds: 5
        periodSeconds: 5

Shipa reports deployment failure if health check fails. If doing canary deployment, next version doesn't get activated until health check passes.

Kubernetes Configuration

If the application is running on a Kubernetes-provisioned framework, Developers can set specific configurations for Kubernetes. These configurations are ignored if the application is running on a Shipa provisioner.

Developers can configure which ports are exposed to each process of the application. Here is a complete example:

kubernetes:
  processes:
    web:
      ports:
       - name: web 
         protocol: TCP
         target_port: 5000
         port: 8080
       - name: socket-port
         protocol: TCP
         port: 4000
    worker:
      ports: []

Each exposed port can be configured for each process using the port's key:

• kubernetes:processes::ports:name: is a descriptive name for the port. This field is optional.
• kubernetes:processes::ports:protocol: defines the port protocol. The accepted values are TCP (default) and UDP.
• kubernetes:processes::ports:target_port: is the port that the process is listening on. If omitted, the port value is used.
• kubernetes:processes::ports:port: is the port that will be exposed on a Kubernetes service. If omitted, the target_port value is used.

If both port and target_port are omitted in a port config, the deployment fails.

Developers can set a process to expose no ports with an empty field, like worker above.

The configuration for multiple ports still has a couple of limitations:

• Healthcheck is set to use the first configured port in each process
• Only the first port of the web process (or the only process, if there is only one) is exposed in the router - but Developers can access the other ports from other applications in the same cluster, using Kubernetes DNS records, like *appname-processname.namespace.svc.cluster.local

Security

Shipa supports secret injection into the application using the HashiCorp Vault product.

Shipa.yaml has a security section where you can define Vault annotations for secret injection.

security:
    vault:
        annotations:
            vault.hashicorp.com/agent-inject: true
            vault.hashicorp.com/role: "internal-app"
            vault.hashicorp.com/agent-inject-secret-config: "internal/data/database/config"
            vault.hashicorp.com/agent-inject-template-config: |
                {{- with secret "internal/data/database/config" -}}
                    postgresql://{{ .Data.data.username }}:{{ .Data.data.password }}@postgres:5432/wizard
                {{- end -}}

Annotate Kubernetes resources managed by Shipa

Provide annotations to be applied to shipa managed kubernetes resources of deployed application such as Ingress, Deployment etc.

kubernetes:
  annotations:
    - kind: Ingress
      values:
        nginx.ingress.kubernetes.io/auth-type: basic
        nginx.ingress.kubernetes.io/auth-secret: basic-auth
        nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required - foo'
    - kind: Deployment
      values:
        key1: val1