Struct shipcat_definitions::manifest::Manifest

pub struct Manifest {

    pub name: String,
    pub publiclyAccessible: bool,
    pub external: bool,
    pub kompass_plugin: bool,
    pub disabled: bool,
    pub regions: Vec<String>,
    pub metadata: Option<Metadata>,
    pub chart: Option<String>,
    pub image: Option<String>,
    pub imageSize: Option<u32>,
    pub version: Option<String>,
    pub command: Vec<String>,
    pub securityContext: Option<SecurityContext>,
    pub dataHandling: Option<DataHandling>,
    pub resources: Option<ResourceRequirements<String>>,
    pub replicaCount: Option<u32>,
    pub env: EnvVars,
    pub secretFiles: BTreeMap<String, String>,
    pub configs: Option<ConfigMap>,
    pub vault: Option<VaultOpts>,
    pub httpPort: Option<u32>,
    pub ports: Vec<Port>,
    pub externalPort: Option<u32>,
    pub health: Option<HealthCheck>,
    pub dependencies: Vec<Dependency>,
    pub destinationRules: Option<Vec<DestinationRule>>,
    pub workers: Vec<Worker>,
    pub sidecars: Vec<Container>,
    pub readinessProbe: Option<Probe>,
    pub livenessProbe: Option<Probe>,
    pub lifecycle: Option<LifeCycle>,
    pub rollingUpdate: Option<RollingUpdate>,
    pub autoScaling: Option<AutoScaling>,
    pub tolerations: Vec<Tolerations>,
    pub hostAliases: Vec<HostAlias>,
    pub initContainers: Vec<Container>,
    pub volumes: Vec<Volume>,
    pub volumeMounts: Vec<VolumeMount>,
    pub persistentVolumes: Vec<PersistentVolume>,
    pub cronJobs: Vec<CronJob>,
    pub serviceAnnotations: BTreeMap<String, String>,
    pub podAnnotations: BTreeMap<String, String>,
    pub labels: BTreeMap<String, String>,
    pub kongApis: Vec<Kong>,
    pub gate: Option<Gate>,
    pub kafka: Option<Kafka>,
    pub sourceRanges: Vec<String>,
    pub rbac: Vec<Rbac>,
    pub eventStreams: Vec<EventStream>,
    pub kafkaResources: Option<KafkaResources>,
    pub newrelic: Option<Newrelic>,
    pub sentry: Option<Sentry>,
    pub upgradeNotifications: Option<NotificationMode>,
    pub region: String,
    pub environment: String,
    pub namespace: String,
    pub uid: Option<String>,
    pub secrets: BTreeMap<String, String>,
    pub state: ManifestState,
    pub workload: PrimaryWorkload,
    pub prometheusAlerts: Vec<PrometheusAlert>,
}

Main manifest, serializable from manifest.yml or the shipcat CRD.

Fields

name: String

Name of the service

This must match the folder name in a manifests repository, and additionally;

• length limits imposed by kube dns
• dash separated, alpha numeric names (for dns readability)

The main validation regex is: ^[0-9a-z\-]{1,50}$.

name: webapp

publiclyAccessible: bool

Whether the service should be public

This is a special flag not exposed to the charts at the moment.

publiclyAccessible: true

external: bool

Service is external

This cancels all validation and marks the manifest as a non-kube reference only.

external: true

kompass_plugin: bool

Whether the service is a kompass plugin

kompassPlugin: true

disabled: bool

Service is disabled

This disallows usage of this service in all regions.

disabled: true

regions: Vec<String>

Regions to deploy this service to.

Every region must be listed in here. Uncommenting a region in here will partially disable this service.

metadata: Option<Metadata>

Important contacts and other metadata for the service

Particular uses:

• notifying correct people on upgrades via slack
• providing direct links to code diffs on upgrades in slack

metadata:
  contacts:
  - name: "Eirik"
    slack: "@clux"
  team: Doves
  repo: https://github.com/clux/blog
  support: "#humans"
  notifications: "#robots"

chart: Option<String>

Chart to use for the service

All the properties in Manifest are tailored towards our base chart, so this should be overridden with caution.

chart: custom

image: Option<String>

Image name of the docker image to run

This can be left out if imagePrefix is set in the config, and the image name also matches the service name. Otherwise, this needs to be the full image name.

image: nginx

imageSize: Option<u32>

Optional uncompressed image size

This is used to compute a more accurate wait time for rolling upgrades. See Manifest::estimate_wait_time.

Ideally, this number is autogenerated from your docker registry.

imageSize: 1400

version: Option<String>

Version aka. tag of docker image to run

This does not have to be set in “rolling environments”, where upgrades re-use the current running versions. However, for complete control, production environments should put the versions in manifests.

Versions must satisfy VersionScheme::verify.

version: 1.2.0

command: Vec<String>

Command to use for the docker image

This can be left out to use the default image command.

command: ["bundle", "exec", "rake", "jobs:work"]

securityContext: Option<SecurityContext>

Extend the workload with a securityContext

This allows changing the ownership of mounted volumes

securityContext:
  runAsUser: 1000
  fsGroup: 1000

dataHandling: Option<DataHandling>

Data sources and handling strategies

An experimental abstraction around GDPR

dataHandling:
  stores:
  - backend: Postgres
    encrypted: true
    cipher: AES256
    fields:
    - name: BabylonUserId
    - name: HealthCheck
  processes:
  - field: HealthCheck
    source: orchestrator

resources: Option<ResourceRequirements<String>>

Kubernetes resource limits and requests

Api straight from kubernetes resources

resources:
  requests:
    cpu: 100m
    memory: 100Mi
  limits:
    cpu: 300m
    memory: 300Mi

replicaCount: Option<u32>

Kubernetes replication count

This is set on the Deployment object in kubernetes. If you have autoScaling parameters set, then these take precedence.

replicaCount: 4

env: EnvVars

Environment variables to inject

These have a few special convenience behaviours: “IN_VAULT” values is replaced with value from vault/secret/folder/service/KEY One off tera templates are calculated with a limited template context

IN_VAULT secrets will all be put in a single kubernetes Secret object. One off templates can be put in a Secret object if marked | as_secret.

env:
  # plain eva:
  RUST_LOG: "tokio=info,raftcat=debug"

  # vault lookup:
  DATABASE_URL: IN_VAULT

  # templated evars:
  INTERNAL_AUTH_URL: "{{ base_urls.services }}/auth/internal"
  REGION_NAME: "{{ region }}"
  NAMESPACE: "{{ namespace }}"

The vault lookup will GET from the region specific path for vault, in the webapp subfolder, getting the DATABASE_URL secret.

secretFiles: BTreeMap<String, String>

Kubernetes Secret Files to inject

These have the same special “IN_VAULT” behavior as Manifest::env: “IN_VAULT” values is replaced with value from vault/secret/folder/service/key

Note the lowercase restriction on keys. All secretFiles are expected to be base64 in vault, and are placed into a kubernetes Secret object.

secretFiles:
  webapp-ssl-keystore: IN_VAULT
  webapp-ssl-truststore: IN_VAULT

configs: Option<ConfigMap>

Config files to inline in a kubernetes ConfigMap

These are read and templated by tera before they are passed to helm. A full tera context from Manifest::make_template_context is used.

configs:
  mount: /config/
  files:
  - name: webhooks.json.j2
    dest: webhooks.json
  - name: newrelic-java.yml.j2

vault: Option<VaultOpts>

Vault options

Allows overriding service names and regions for secrets. DEPRECATED. Should only be set in rare cases.

httpPort: Option<u32>

Http Port to expose in the kubernetes Service

This is normally the service your application listens on. Kong deals with mapping the port to a nicer one.

httpPort: 8000

ports: Vec<Port>

Ports to open

For services outside Kong, expose these named ports in the kubernetes Service.

 ports:
 - port: 6121
   name: data
 - port: 6122
   name: rpc
 - port: 6125

externalPort: Option<u32>

Externally exposed port

Useful for LoadBalancer type Service objects.

externalPort: 443

health: Option<HealthCheck>

Health check parameters

A small abstraction around readinessProbe. DEPRECATED. Should use readinessProbe.

health:
  uri: /health
  wait: 15

dependencies: Vec<Dependency>

Service dependencies

Used to construct a dependency graph, and in the case of non-circular trees, it can be used to arrange deploys in the correct order.

dependencies:
- name: auth
- name: ask2
- name: chatbot-reporting
- name: clinical-knowledge

destinationRules: Option<Vec<DestinationRule>>

Destination Rules

The intention here is that implementations will examine requests to determine if they satisfy this rule and if so, redirect them to alternative services as specified by ‘host’.

For an example, one could implement destination rules using an Istio virtual service which matched on inbound request header values to determine whether to apply this rule and redirect the request.

destinationRules:
- identifier: 'USA'
  host: 'service.com'

workers: Vec<Worker>

Worker Deployment objects to additionally include

These are more flexible than sidecars, because they scale independently of the main replicaCount. However, they are considered separate rolling upgrades. There is no guarantee that these switch over at the same time as your main kubernetes Deployment.

workers:
- name: analytics-experiment-taskmanager
  resources:
    limits:
      cpu: 1
      memory: 1Gi
    requests:
      cpu: 250m
      memory: 1Gi
  replicaCount: 3
  preserveEnv: true
  ports:
  - port: 6121
    name: data
  - port: 6122
    name: rpc
  - port: 6125
    name: query
  command: ["/start.sh", "task-manager", "-Djobmanager.rpc.address=analytics-experiment"]

sidecars: Vec<Container>

Sidecars to inject into every kubernetes Deployment

Plain sidecars are injected into the main Deployment and all the workers’ ones. They scale directly with the sum of replicaCounts.

sidecars:
- name: redis

readinessProbe: Option<Probe>

readinessProbe for kubernetes

This configures the service’s health check, which is used to gate rolling upgrades. Api is a direct translation of kubernetes liveness/readiness probes.

This replaces shipcat’s Manifest::health abstraction.

readinessProbe:
  httpGet:
    path: /
    port: http
    httpHeaders:
    - name: X-Forwarded-Proto

livenessProbe: Option<Probe>

livenessProbe for kubernetes

This configures a livenessProbe check. Similar to readinessProbe, but with the instruction to kill the pod on failure. Api is a direct translation of kubernetes liveness/readiness probes.

livenessProbe:
  tcpSocket:
    port: redis
  initialDelaySeconds: 15
  periodSeconds: 15

lifecycle: Option<LifeCycle>

Container lifecycle events for kubernetes

This allows commands to be executed either postStart or preStop https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/

rollingUpdate: Option<RollingUpdate>

Rolling update Deployment parameters

These tweak the speed and care kubernetes uses when doing a rolling update. Sraight from kubernetes rolling update parameters. This is attached onto the main Deployment.

rollingUpdate:
  maxUnavailable: 0%
  maxSurge: 50%

autoScaling: Option<AutoScaling>

HorizontalPodAutoScaler parameters for kubernetes

Passed all parameters directly onto the spec of a kube HPA. Straight from kubernetes horizontal pod autoscaler.

autoScaling:
  minReplicas: 6
  maxReplicas: 9
  metrics:
  - type: Resource
    resource:
      name: cpu
      targetAverageUtilization: 60

tolerations: Vec<Tolerations>

Toleration parameters for kubernetes

Bind a service to a particular type of kube Node. Straight from kubernetes taints and tolerations.

tolerations:
- key: "dedicated"
  operator: "Equal"
  value: "hugenode"
  effect: "NoSchedule"

hostAliases: Vec<HostAlias>

Host aliases to inject in /etc/hosts in every kubernetes Pod

Straight from kubernetes host aliases.

hostAliases:
- ip: "160.160.160.160"
  hostnames:
  - weird-service.babylontech.co.uk

initContainers: Vec<Container>

initContainer list for every kubernetes Pod

Allows database connectivity checks to be done as pre-boot init-step. Straight frok kubernetes init containers.

initContainers:
- name: init-cassandra
  image: gophernet/netcat
  command: ['sh', '-c', 'until nc -z dev-cassandra 9042; do sleep 2; done;']

volumes: Vec<Volume>

Volumes that can be mounted in every kubernetes Pod

Supports our subset of kubernetes volumes

volumes:
- name: google-creds
  secret:
    secretName: google-creds
    items:
    - key: file
      path: google-cloud-creds.json
      mode: 0o777

volumeMounts: Vec<VolumeMount>

Volumes to mount to every kubernetes Pod

Requires the Manifest::volumes entries. Straight from kubernetes volumes

volumeMounts:
- name: ssl-store-files
  mountPath: /conf/ssl/
  readOnly: true

persistentVolumes: Vec<PersistentVolume>

PersistentVolumes for the deployment

Exposed from shipcat, but not overrideable. Mostly straight from kubernetes persistent volumes.

persistentVolumes:
- name: svc-cache-space
  mountPath: /root/.scratch
  size: 10Gi

cronJobs: Vec<CronJob>

Cronjob images to run as kubernetes CronJob objects

Limited usefulness abstraction, that should be avoided. An abstraction on top of kubernetes cron jobs

cronJobs:
- name: webapp-promotions-expire
  schedule: "1 0 * * *"
  command: ["bundle", "exec", "rake", "cron:promotions:expire", "--silent"]

serviceAnnotations: BTreeMap<String, String>

Annotations to set on Service objects

Useful for LoadBalancer type Service objects. Not useful for kong balanced services.

serviceAnnotations:
  svc.k8s.io/aws-load-balancer-ssl-cert: arn:aws:acm:eu-west-2:12345:certificate/zzzz
  svc.k8s.io/aws-load-balancer-backend-protocol: http
  svc.k8s.io/aws-load-balancer-ssl-ports: "443"
  svc.k8s.io/aws-load-balancer-ssl-negotiation-policy: ELBSecurityPolicy-TLS-1-2-2018-01
  helm.sh/resource-policy: keep

podAnnotations: BTreeMap<String, String>

Metadata Annotations for pod spec templates in deployments, and cron jobs

https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

podAnnotations:
  iam.amazonaws.com/role: role-arn

labels: BTreeMap<String, String>

Labels for every kubernetes object

Injected in all top-level kubernetes object as a prometheus convenience. https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/

labels:
  custom-metrics: true

kongApis: Vec<Kong>

Kong config

A mostly straight from API configuration struct for Kong Work in progress. structs::kongfig contain the newer abstractions.

kong:
  uris: /webapp
  strip_uri: true

gate: Option<Gate>

Deprecated Gate config

Do not use.

kafka: Option<Kafka>

Kafka config

A small convencience struct to indicate that the service uses Kafka, and to define kafka-specific properties. if this is set to a Some.

kafka: {}

sourceRanges: Vec<String>

Load balancer source ranges

This is useful for charts that expose a Service of LoadBalancer type. IP CIDR ranges, which Kubernetes will use to configure firewall exceptions.

sourceRanges:
- 0.0.0.0/0

rbac: Vec<Rbac>

Role-Based Access Control

A list of resources to allow the service access to use. This is a subset of kubernetes Role::rules parameters.

rbac:
- apiGroups: ["extensions"]
  resources: ["deployments"]
  verbs: ["get", "watch", "list"]

eventStreams: Vec<EventStream>

Kafka / EventStream configuration

A list of resources that will interact with the Kafka-operator CRD / service to create kafka topics and ACLs. The Kafka-Operator is an extension of the strimzi-kafka-operator project:

• https://strimzi.io/
• https://github.com/strimzi/strimzi-kafka-operator

 eventStreams:
 - name: topicA
   producers:
   - service1
   - service2
   consumers:
   - service3
   - service4
   eventDefinitions:
   - key: my_schema_key
     value: my_schema_value
   - key: my_schema_key_1
     value: my_schema_value_1
   config:
       retention.ms: "7200000"
       segment.bytes: "1073741824"

kafkaResources: Option<KafkaResources>

Kafka Resources (Topics and Users)

inputs for this struct relate directly to the strimzi kafka project. Topic Inputs: Strimzi Kafka Topic CRD User Inputs: Strimzi Kafka User CRD

kafkaResources:
  topics:
  - name: foo-topic-name
    partitions: 1
    replicas: 3
    config:
      retention.ms: 604800000
      segment.bytes: 1073741824
  users:
  - name: foo-user-name
    acls:
    - resourceName: testtopic
      resourceType: topic
      patternType: literal
      operation: write
      host: "*"
    - resourceName: testtopic
      resourceType: topic
      patternType: literal
      operation: read
      host: "*"

newrelic: Option<Newrelic>

Monitoring section covering NewRelic configuration

newrelic:
  alerts:
    alert_name_foo:
      name: alert_name_foo:
      template: appdex
      params:
        threshold: "0.5"
        priority: critical
  incidentPreference: PER_POLICY
  slack: C12ABYZ78

sentry: Option<Sentry>

Monitoring section covering Sentry configuration

sentry:
  slack: C12ABYZ78
  silent: false

upgradeNotifications: Option<NotificationMode>

Slack upgrade notification settings

upgradeNotifications: Silent

region: String

Region injected into helm chart

Exposed from shipcat, but not overrideable.

environment: String

Environment injected into the helm chart

Exposed from shipcat, but not overrideable.

namespace: String

Namespace injected in helm chart

Exposed from shipcat, but not overrideable.

uid: Option<String>

Uid from the CRD injected into the helm chart

This is required to inject into the charts due to https://github.com/kubernetes/kubernetes/issues/66068

Exposed from shipcat, but not overrideable.

secrets: BTreeMap<String, String>

Raw secrets from environment variables.

The env map fills in secrets in this via the vault client. Manifest::secrets partitions env into env and secrets. See Manifest::env.

This is an internal property that is exposed as an output only.

state: ManifestState

Internal state of the manifest

A manifest goes through different stages of serialization, templating, config loading, secret injection. This property keeps track of it.

workload: PrimaryWorkload

The default workload associated with a Manifest

Defaults to Deployment

workload: Statefulset

prometheusAlerts: Vec<PrometheusAlert>

Prometheus alerts associated with the service.

prometheusAlerts:
- name: AlertNameInPascalCase
  summary: "One-line summary of the issue"
  description: "More details about the issue, supports Prometheus label templating"
  expr: "rate(my_service_error_rate_metric[5m]) > 123"
  min_duration: 15m
  severity: warning

Implementations

impl Manifest

pub fn version(self, version: String) -> Self

Set the version field

pub fn print(&self) -> Result<()>

Print manifest to stdout

pub fn verify_region(&self) -> Result<&Self>

Verify the region for this manifest is one of its declared ones

Assumes the manifest has been populated with implicits

pub fn verify_destination_rules(&self, region: &Region) -> Result<()>

Verifies the “destinationRules” manifest entries if they are configured

It is erroneous to define destination rules without configuring the corresponding region’s destination rules host regular expression

pub fn verify(&self, conf: &Config, region: &Region) -> Result<()>

Verify assumptions about manifest

Assumes the manifest has been populated with implicits

pub fn get_env_vars(&mut self) -> Vec<&mut EnvVars>

pub async fn secrets(&mut self, client: &Vault, vc: &VaultConfig) -> Result<()>

Populate placeholder fields with secrets from vault

This will use the HTTP api of Vault using the configuration parameters in the Config.

pub fn get_secrets(&self) -> Vec<String>

Get a list of raw secrets (without associated keys)

Useful for obfuscation mechanisms so it knows what to obfuscate.

pub async fn verify_secrets_exist(&self, vc: &VaultConfig) -> Result<()>

impl Manifest

pub fn test(name: &str) -> Manifest

impl Manifest

This library defines the way to upgrade a manifest from Base but each backend has to implement its own way of:

• listing services from its backing
• creating a base manifest from its backing

pub async fn stub(self, reg: &Region) -> Result<Self>

Complete a Base manifest with stub secrets

pub async fn complete(self, reg: &Region) -> Result<Self>

Complete a Base manifest with actual secrets

pub fn is_base(&self) -> bool

Check to see we are using the right types of manifests internally

impl Manifest

Calculations done based on values in manifests

These generally assume that verify has passed on all manifests.

pub fn min_replicas(&self) -> u32

Compute minimum replicas

Used to estimate_rollout_iterations for a rollout.

pub fn estimate_rollout_iterations(&self) -> u32

Estimate how many iterations needed in a kube rolling upgrade

Used to estimate_wait_time for a rollout.

pub fn estimate_wait_time(&self) -> u32

Estimate how long to wait for a kube rolling upgrade

Was used by helm, now used by the internal upgrade wait time.

pub fn compute_resource_totals(&self) -> Result<ResourceTotals>

Compute the total resource usage of a service

This relies on the Mul and Add implementations of ResourceRequirements<f64>, which allows us to do + and * on a normalised ResourceRequirements struct.

impl Manifest

pub fn template_configs(&mut self, reg: &Region) -> Result<()>

Replace template in values with template result inplace

pub fn template_evars(&mut self, reg: &Region) -> Result<()>

Template evars - must happen before inline templates!

Trait Implementations

impl Clone for Manifest

fn clone(&self) -> Manifest

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Manifest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Manifest

fn default() -> Manifest

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Manifest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl From<Manifest> for ShipcatManifest

fn from(mf: Manifest) -> ShipcatManifest

Performs the conversion.

impl Serialize for Manifest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.