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.