github.com/munnerz/test-infra@v0.0.0-20190108210205-ce3d181dc989/prow/pod-utilities.md (about)

     1  # Pod Utilities
     2  
     3  Pod utilities are small, focused Go programs used by `plank` to decorate user-provided `PodSpec`s
     4  in order to increase the ease of integration for new jobs into the entire CI infrastructure. The
     5  utilities today wrap the execution of the test code to ensure that the tests run against correct
     6  versions of the source code, that test commands run in the appropriate environment and that output
     7  from the test (in the form of status, logs and artifacts) is correctly uploaded to the cloud.
     8  
     9  These utilities are integrated into a test run by adding `InitContainer`s and sidecar `Container`s
    10  to the user-provided `PodSpec`, as well as by overwriting the `Container` entrypoint for the test
    11  `Container` provided by the user. The following utilities exist today:
    12  
    13   - [`clonerefs`](./cmd/clonerefs/README.md): clones source code under test
    14   - [`initupload`](./cmd/initupload/README.md): records the beginning of a test in cloud storage
    15     and reports the status of the clone operations
    16   - [`entrypoint`](./cmd/entrypoint/README.md): is injected into the test `Container`, wraps the
    17     test code to capture logs and exit status
    18   - [`sidecar`](./cmd/sidecar/README.md): runs alongside the test `Container`, uploads status, logs
    19     and test artifacts to cloud storage once the test is finished
    20  
    21  ## Writing a ProwJob that uses Pod Utilities
    22  
    23  ### What the test container can expect
    24  
    25  Example test container script:
    26  ```bash
    27  pwd # my repo root
    28  ls path/to/file/in/my/repo.txt # access repo file
    29  ls ../other-repo # access repo file in another repo
    30  echo success > $ARTIFACTS/results.txt # result info that will be uploaded to GCS.
    31  # logs, and job metadata are automatically uploaded.
    32  ```
    33  
    34  More specifically, a ProwJob using the Pod Utilities can expect the following:
    35  - **Source Code** - Jobs can expect to begin execution with their working
    36  directory set as the root of the checked out repo. The commit that is checked
    37  out depends on the type of job:
    38  	- `presubmit` jobs will have the relevant PR checked out and merged with the base branch.
    39  	- `postsubmit` jobs will have the upstream commit that triggered the job checked out.
    40  	- `periodic` jobs will have the working directory set to the root of the repo specified by the first ref in `extra_refs` (if specified).
    41  See the `extra_refs` field if you need to clone more than one repo.
    42  - **Metadata and Logs** - Jobs can expect metadata about the job to be uploaded
    43  before the job starts, and additional metadata and logs to be uploaded when the
    44  job completes.
    45  - **Artifact Directory** - Jobs can expect an `$ARTIFACTS` environment variable
    46  to be specified. It indicates an existent directory where job artifacts can be
    47  dumped for automatic upload to GCS upon job completion.
    48  
    49  ### How to configure
    50  
    51  ProwJobs may request Pod Utility decoration by setting `decorate: true` in their config.
    52  Example ProwJob configuration:
    53  ```yaml
    54  
    55    - name: pull-job
    56      always_run: true
    57      decorate: true
    58      spec:
    59        containers:
    60        - image: alpine
    61          command:
    62          - "echo"
    63          args:
    64          - "The artifacts dir is $(ARTIFACTS)"
    65  ```
    66  
    67  In addition to normal ProwJob configuration, ProwJobs using the Pod Utilities
    68  must specify the `command` field in the container specification instead of using
    69  the Dockerfile's ENTRYPOINT directive. Note that the `command` field is a string
    70  array not just a string. It should point to the test binary location in the container.
    71  
    72  Additional fields may be required for some use cases:
    73  - Private repos need to do two things:
    74  	- Add an ssh secret that gives the bot access to the repo to the build cluster
    75  	and specify the secret name in the `ssh_key_secrets` field of the job decoration config.
    76  	- Set the `clone_uri` field of the job spec to `git@github.com:{{.Org}}/{{.Repo}}.git`.
    77  - Repos requiring a non-standard clone path can use the `path_alias` field
    78  to clone the repo to different go import path than the default of `/home/prow/go/src/github.com/{{.Org}}/{{.Repo}}/` (e.g. `path_alias: k8s.io/test-infra` -> `/home/prow/go/src/k8s.io/test-infra`).
    79  - Jobs that require additional repos to be checked out can arrange for that with
    80  the `exta_refs` field.
    81  - Jobs that do not want submodules to be cloned should set `skip_submodules` to `true`
    82  
    83  ```yaml
    84  - name: post-job
    85    decorate: true
    86    decoration_config:
    87      ssh_key_secrets:
    88      - ssh-secret
    89    clone_uri: "git@github.com:<YOUR_ORG>/<YOUR_REPO>.git"
    90    extra_refs:
    91    - org: kubernetes
    92      repo: other-repo
    93      base_ref: master
    94    skip_submodules: true
    95    spec:
    96      containers:
    97      - image: alpine
    98        command:
    99        - "echo"
   100        args:
   101        - "The artifacts dir is $(ARTIFACTS)"
   102  
   103  ```
   104  
   105  ### Why use Pod Utilities?
   106  
   107  Writing a ProwJob that uses the Pod Utilities is much easier than writing one
   108  that doesn't because the Pod Utilities will transparently handle many of the
   109  tasks the job would otherwise need to do in order to prepare its environment
   110  and output more than pass/fail. Historically, this was achieved by wrapping
   111  every job with a [bootstrap.py](jenkins/bootstrap.py) script that handled cloning
   112  source code, preparing the test environment, and uploading job metadata, logs,
   113  and artifacts. This was cumbersome to configure and required every job to be
   114  wrapped with the script in the job image. The pod utilities achieve the same goals
   115  with less configuration and much simpler job images that are easier to develop
   116  and less coupled to Prow.