Skip to content
This repository has been archived by the owner on Apr 29, 2020. It is now read-only.

Pod Manifests

Jump to bottom
Stephen Jung edited this page Apr 20, 2015 · 13 revisions

Applications in p2 are deployed by providing a central Intent Store with information that is consumed by preparers running on hosts in your cluster. The primary means to provide data to the intent store is by using pod manifests.

Pod manifests are YAML files that contain information about collections of executable Hoist artifacts and their runtime configuration. In this document we'll go over the basic schema of pod manifests and how they are used.

While manifests are stored in the intent store, the github.com/square/p2/pods library is intended to be standalone - that is, one could write a quick command line tool to do installs using just this library and abstain from p2's use of Consul altogether. This utility is already part of p2 (see p2-launch).

All pod manifests must be clearsigned with a PGP key for the preparer to deploy them. If the preparer cannot identify the signer of a manifest (or if it's not signed at all), that manifest will be ignored.

(The concept of a pod manifest was borrowed from Kubernetes, Google's container orchestration framework)

Top-level metadata

The 1.0 version of the p2 manifest schema defines the following fields.

  • id - The unique identifier for the pod. One pod of a given ID should exist on a box at any given time. The ID of the pod will be used to name folders and services on the machine. All Hoist launchables in the pod will be run under the user named after the ID.
  • version - (optional) this specifies the version of the schema to use. By default it is the earliest supported version (right now 1.0a)
  • launchables - this is a map of artifact IDs to their locations for download. Each launchable specifies a type. As of writing, the only supported type is hoist but future types will become available.
  • config - A freeform value that will be written as a config file for consumption by launched applications via the CONFIG_PATH environment variable. Configuration between launchables is shared, and no additional manipulation of the config is done beyond the values entered into the pod manifest. For macros, namespacing, templating, or generated configs, clients will need to write their own orchestration.
  • status_port - A port number with a /_status endpoint, that p2 should use for HTTP-based health checks. See Health Checks for more details.

Launchables

The launchables key enumerates the various components that make up a pod. This gives developers the flexibility to plug a single project into multiple pods. For example, you may wish to have a single repeatable build for stunnel that can be plugged into multiple pods. An example launchables stanza might look like this:

launchables:
  preparer:
    launchable_type: hoist
    launchable_id: preparer
    location: https://artifact-repo.com/p2-preparer_9617dd90b99b28b0671887f6e3e785a7d9f75a0a.tar.gz
    cgroup:
      cpus: 3
      memory: 123456
  p2logconsumer:
    launchable_type: hoist
    launchable_id: p2logconsumer
    location: https://artifact-repo.com/p2logconsumer_3a52d321f47474f34bcdea59514dd516069e430a.tar.gz
    container: small
    digest_location: https://artifact-repo.com/p2logconsumer_3a52d321f47474f34bcdea59514dd516069e430a.tar.gz.sum
    digest_signature_location: https://artifact-repo.com/p2logconsumer_3a52d321f47474f34bcdea59514dd516069e430a.tar.gz.sum.sig

The above defines two launchables in the pod, both of type hoist (see Hoist Artifacts) and having unique launchable_id fields to identify them. The location field tells the preparer where to download the artifacts from. The artifacts are versioned so we can be explicit about what version of each project we are deploying. In this case, we are deploying the p2 preparer itself, along with a buddy launchable called p2logconsumer whose job it is to consume log messages from the preparer and dump them into Kafka.

The cgroup field tells p2 how much cgroup limiting to apply to the hoist launchable's contents. Right now only two subsystems are supported, cpus (specify the number of logical cores) and memory (the number of bytes).

The digest_location and digest_signature_location field enable SHA256 verification for the hoist artifact's contents. For more details, refer to the page on Hoist artifacts.

Configuration

The config stanza allows developers to specify config for the launchables to be written by p2. An example config stanza might be:

config:
  preparer:
    consul_host: localhost:8300
    extra_log_destinations:
    - type: socket
      path: /data/pods/p2-preparer/log.sock
  p2logconsumer:
    log_input:
      type: socket
      path: /data/pods/p2-preparer/log.sock

Everything under the config stanza will be written to a yaml file on disk, with the path to that file passed in the CONFIG_PATH environment variable to the deployed processes. The launchables can be written to consume config from this file. In the above example, we are hooking up the preparer's log destination with the p2logconsumer to form a logging "pipe" of sorts.

A more complex example

Pod manifests are intended to capture both the code that needs to run as well as its runtime configuration. Anytime a change is detected in a pod manifest, the preparer assigned to it will try to reconcile the differences in the manifest and restart all of launchables therein.

In this manifest, we have three launchables, one is a web service that accepts many types of requests. The second is a log processor that consumes the log output from the web application. The third is a redis pod configured to act as a Sidekiq work queue.

id: carsales.com
launchables:
  web:
    launchable_type: hoist
    launchable_id: web
    location: https://carsales.internal/web-releases/web_af7d29ef.tar.gz
  redis:
    launchable_type: hoist
    launchable_id: redis
    location: https://carsales.internal/redis-releases/redis_73910efab.tar.gz
  logs:
    launchable_type: hoist
    launchable_id: logs
    location: https://carsales.internal/logs-releases/logs_1182fbce.tar.gz
config:
  log_destination: /var/logs/carsales.com.log
  redis:
    port: 6380
  web:
    port: 8000

When this pod is deployed, all three artifacts will be installed on the node the manifest is assigned to. The configuration stanza now has content; a configuration file containing just that stanza will be made available to all launchables via the CONFIG_PATH environment variable.

Clone this wiki locally