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. This health check is called during the deployment process. Shipa confirms this health check is passing before continuing with it.

If Shipa fails to run the health check successfully, it aborts the deployment before switching the router to point to the new units. Therefore, the application is never unresponsive.

Developers can configure a health check in the YAML file using the following example:

healthcheck:
  path: /healthcheck
  scheme: http
  allowed_failures: 0

• healthcheck:path: defines which path to call in the application. This path is called for each unit. It is the only mandatory field. If not set, the health check is ignored
• healthcheck:scheme: defines which scheme to use. The defaults is http.
• healthcheck:allowed_failures: specifies the number of allowed failures before healthcheck considers the application is unhealthy. The defaults is 0.
• healthcheck:timeout_seconds: is the timeout for each healthcheck call in seconds. The default is 60 seconds.
• healthcheck:interval_seconds: is exclusive to Kubernetes Provisioner. It is the interval in seconds between each active healthcheck call if use_in_router is set to true. The default is 10 seconds.
• healthcheck:force_restart: is exclusive to Kubernetes Provisioner. It determines whether the unit should be restarted after allowed_failures encounters consecutive healthcheck failures. (Sets the liveness probe in the Pod.

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 -}}