sip.yml (SIP Application Template)

The SIP Application Template is the central mechanism that a developer uses to specify how the application will be deployed on the SIP. The SIP Application Template is specified in the form of a yaml file called sip.yml that should be placed in the root of the application repository.

This page describes in detail all the configuration options that are currently available using the SIP Application Template.

Currently the following resources and mechanisms can be configured using the SIP Application template:

The following as a complete example of a typical SIP Application Templates. It requests a Postgres database and access to S3 Storage. It also requests a randomly generated secret for SECRET_TEST and it listens on port 8080 and is by default accessible on not.<organisation-domain>

 env:
 - name: TEST
   value: "hohooooo"
 - name: SECRET_TEST
   secret:
     key: test
   	 create: random
 postgres:
 - name: blub
   constraint:
   min: 9.3.1
 s3:
 - name: foo
 ingress:
 - subdomain: not
   http:
   - path: /
     port: 8080

Database

Postgres

This field is a list of Postgres Databases. For every item in this list, a new database will be created. The constraint can request a minimal and maximal Postgres version. You can also leave it blank.

The information necessary to connect to each of the databases will then be injected into the container as environment variables:

• SIP_POSTGRES_<NAME>_SERVER: The URL of the server to connect to
• SIP_POSTGRES_<NAME>_PORT: The port of the server to connect to
• SIP_POSTGRES_<NAME>_NAME: The name of the database to connect to
• SIP_POSTGRES_<NAME>_USER: The username for the postgres database
• SIP_POSTGRES_<NAME>_PW: The password for the postgres database

The <NAME> represents the uppercase name field given in the SIP template, with dashes replaced by underscores.

postgres:
 - name: blub
   constraint:
   min: 9.3.1

MySQL

This field is a list of MySQL Databases. For every item in this list, a new database will be created. The constraint can request a minimal and maximal MySQL version. You can also leave it blank.

The information necessary to connect to the database will then be injected into the container as environment variables.

• SIP_MYSQL_<NAME>_SERVER: The URL of the server to connect to
• SIP_MYSQL_<NAME>_PORT: The port of the server to connect to
• SIP_MYSQL_<NAME>_NAME: The name of the database to connect to
• SIP_MYSQL_<NAME>_USER: The username for the MySQL database
• SIP_MYSQL_<NAME>_PW: The password for the MySQL database

mysql:
 - name: blub
   constraint:
   min: 4.3.1

Storage

S3

This field is a list of S3 buckets. For every item in this list, a new bucket will be created. Our S3 supports pre-signed URLs

The information necessary to connect to each of the buckets will then be injected into the container as environment variables:

• SIP_S3_<NAME>_HOST: The URL of the server to connect to
• SIP_S3_<NAME>_PORT: The port of the server to connect to
• SIP_S3_<NAME>_BUCKET: The name of the bucket to connect to
• SIP_S3_<NAME>_ACCESS_KEY: The access key for the bucket
• SIP_S3_<NAME>_SECRET_KEY: The secret key for the bucket
• SIP_S3_<NAME>_USE_SSL: Whether to use SSL to connect to the bucket

The <NAME> represents the name field given in the SIP template.

s3:
 - name: foo

Volumes

This is a list of requested persistent volumes. Each list item needs to have a name and the complete spec of a persistent volume claim

 volumes:
 - name: foo
   mountPath: "/mnt/foo"
   accessModes:
   - ReadWriteOnce
   resources:
     requests:
       storage: 5Gi

Network

Ingress

This field will make your application accessible from the outside world. You will have to provide on which subdomain you want to be accessible and on what path and port you are listening.

The example below will forward http traffic arriving at not.<organisation-domain> to your application on port 8080 and add an alias for the domain at also-not.example.

We also support the addition of arbitrary Annotations. Ingresses of the same type [http, grpc, grpcweb] will be joined and conflicting annotations will lead to undefined behaviour.

ingress:
 - name: default
   subdomain: not
   annotations:
     foo: "bar"
     test: "3"
   cnames:
    - also-not.example
   http:
   - path: /
     port: 8080

The example below will expose a gRPC API running on port 7777

ingress:
 - name: default
   subdomain: not
   grpc:
   - port: 7777

If you walso want to expose the API using grpc Web:

ingress:
 - name: default
   subdomain: api.test
   grpc:
   - port: 7777
 - name: grpcweb
   subdomain: webapi.test
   grpc-web:
   - port: 7777

Several variables for each ingress will then be injected into the container as environment variables which can then be used e.g. for setting the CSP of a site:

• SIP_INGRESS_<NAME>_DEPLOYMENT_DOMAIN: The primary deployment domain of the ingress consisting of both the subdomain and the base domain
• SIP_INGRESS_<NAME>_CNAMES: A space separated list of domains that were set as CNAME records

Change Maximal Upload Size and PHP Memory Limit of the Nginx and PHP Base Images

You can adjust Nginx/PHP's upload limit and memroy limit with built-in environment variables of the base images. But you also have to adjust Ingress. Here is an example. If you do not have PHP you can skip all the environment variables with CUSTOM_PHP*.

ingress:
  name: http-default
  subdomain: app-domain
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 512m

env:
- name: CUSTOM_NGINX_MAX_BODY_SIZE
  value: 512m
- name: CUSTOM_PHP_MEMORY_LIMIT
  value: 256m
- name: CUSTOM_PHP_POST_MAX_SIZE
  value: 512m
- name: CUSTOM_PHP_UPLOAD_MAX_FILESIZE
  value: 500m

Environment Variables

This field is a list of environment variables that are set for the application.

These are either fixed values, values that need to be set by the organisation deploying the application, secrets, or values that can be read from the namespace the application is deployed into.

We support different kinds of environment variables:

• Basic: These are fixed environment variables. These are usually used by developers to set global configuration without hard coding them into the application itself. Every deployment of this applications will use the same values.

  Example

  - name: TEST  
    value: "hohooooo"

• Secret: These are values that are unique to a deployment and that are secret. We have two different ways to create a secret "random" and "provided".

  • "provided": The secret needs to be provided by the user. The corresponding key in the secret will be set to "". The actual secret needs to be entered into the secret by the user.
  • "random": A random 16 character secret will be generated, using "a-z;A-Z;1-9"
  Example

  - name: SECRET_TEST 
    secret: 
      key: test 
      create: random

The environment variable will then be accessible to the application as an EnvVar with the given Name.

 env:
 - name: TEST
   value: "hohooooo"
 - name: SECRET_TEST
   secret:
   key: test
   create: random

SMTP

SIP can provide you a possibility to send Mails via SMTP. The same service account can also be used to send mails per GRPC

The information for connecting to the SMTP server will be provided to you during runtime:

The minimal set of information:

• SIP_SMTP_<NAME>_MAIL_USER: The username for the SMTP connection.
• SIP_SMTP_<NAME>_MAIL_PW: The password for the SMTP connection.

Redzone: mail-api-smtp.api-prod.svc.cluster.local port 8081without any encryption

We a currently working that all these information also are provided as environment variables.

• SIP_SMTP_<NAME>_FROM_MAIL: The E-Mail address that you have to set as a sender of E-Mails.
• SIP_SMTP_<NAME>_HOST: The Hostname of the SMTP server.
• SIP_SMTP_<NAME>_ENCRYPTION: If you should use STARTTLS for the SMTP connection (can be 'true' or 'false').
• SIP_SMTP_<NAME>_PORT: The Port for the SMTP server.

Set the needed information in the sip.yml:

smtp:
 - name: thirdpartyapp

Authentication and Authorization

MANUAL STEP

Information about auth services are also passed by environment variables. 

auth:
- name: test-application-frontend
  accessType: public
  clientProtocol: openid-connect
  validRedirectURIs:
    - https://yourapplication.vseth.ethz.ch/callback
  scopes:
    defaultClientScopes:
      - profile
      - email
    optionalClientScopes:
      - address
- name: test-application-backend
  accessType: bearer
  roles: 
    - name: admin
      description: Admin of the application
    - name: not-admin
      description: Not-admins of the application

Client independent

These variables are independent of the client you are using:

{
  "keys": [
    {
      "kid": "xxfdsafefesa",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "fdsafdsa",
      "e": "AQAB",
      "x5c": [
        "fdsafesa"
      ],
      "x5t": "v-3hmaHcRvHUU18Dj5MAQC0MB9c",
      "x5t#S256": "ZXWD5GtYyteHUfVXUbhILrNDhj0JzZhwG5GJVWIQHKM"
    }
  ]
}

SIP_AUTH_OIDC_ISSUER

Client dependent

These variables depend on the client name you specified in sip.yml, should replace <name>.

API Access

MANUAL STEP

Currently the variables to access APIs have to be set by hand. Since this will be change soon only the standardized variables should be used.

If you consume an API you simply have to add the servis name to the consumes list

servis:
  consumes:
  - name: "vseth.sip.people"

If you provide an API you will have to at least reference the corresponding Ingress

ingress:
  - name: default
    subdomain: people.api
    grpc:
      - port: 9111
  - name: web
    subdomain: people.webapi
    grpc-web:
      - port: 9111
servis:
  provides:
  - name: "vseth.sip.people"
    ingress: default
    webingress: web
    ssl: false

Kubernetes Internal

Resources

Sets the resource requirements of the application container. See official kubernetes documentation for further information.

 resources:
   requests:
     memory: 50Mi
     cpu: 100m
   limits:
      memory: 100Mi
      cpu: 500m

Node Selectors

These are only listed for completeness and usage is not recommended!

nodeSelector:
  graphicSettings: ultra
  miningProfile: monero
  data: big

Prometheus configuration

If your application exports metrics for Prometheus, you can specify the port and the path to the metrics endpoint.

prometheus:
  port: 9100
  path: "/prom"

Port is required, path is optional and will default to /metrics if not specified.