k8s.io/test-infra@v0.0.0-20240520184403-27c6b4c223d8/images/builder/README.md (about)

     1  # image-builder
     2  
     3  This builder is sugar on top of `gcloud builds submit`. It offers the following features:
     4  
     5  - Automatically injecting the standard commit-based tag (e.g. `20190403-dddd315ad-dirty`) as `_GIT_TAG`
     6  - Optionally blocking pushes of dirty builds
     7  - Uploading the working directory to GCS once and then reusing it for several builds
     8  - Building multiple variants simultaneously and optionally sending their output to files
     9  
    10  A "variant" is a group of GCB substitutions grouped together to describe several ways to build a
    11  given image. They are optionally defined in `variants.yaml` in the same folder as the `Dockerfile`
    12  and `cloudbuild.yaml`. For example, a subset of the `kubekins-e2e` variants looks like this:
    13  
    14  ```yaml
    15  variants:
    16    '1.16':
    17      CONFIG: '1.16'
    18      GO_VERSION: 1.13.5
    19      K8S_RELEASE: stable-1.16
    20      BAZEL_VERSION: 0.23.2
    21    '1.15':
    22      CONFIG: '1.15'
    23      GO_VERSION: 1.12.12
    24      K8S_RELEASE: stable-1.15
    25      BAZEL_VERSION: 0.23.2
    26  ```
    27  
    28  By default, the image builder will build both the `1.15` and `1.16` groups simultaneously.
    29  If `--log-dir` is specified, it will write the build logs for each to `1.15.log` and `1.16.log`.
    30  
    31  Alternatively, you can use `--variant` to build only one variant, e.g. `--variant 1.15`.
    32  
    33  If no `variants.yaml` is specified, `cloudbuild.yaml` will be run once with no extra substitutions
    34  beyond `_GIT_TAG`.
    35  
    36  ## Usage
    37  
    38  ```shell
    39  go run ./images/builder [options] path/to/build-directory/
    40  ```
    41  
    42  - `--allow-dirty`: If true, allow pushing dirty builds.
    43  - `--log-dir`: If provided, build logs will be sent to files in this directory instead of to stdout/stderr.
    44  - `--project`: If specified, use a non-default GCP project.
    45  - `--scratch-bucket`: If provided, the complete GCS path for Cloud Build to store scratch files (sources, logs). Necessary for upload reuse. If omitted, `gcloud` will create or reuse a bucket of its choosing.
    46  - `--variant`: If specified, build only the given variant. An error if no variants are defined.
    47  - `--env-passthrough`: Comma-separated list of specified environment variables to be passed to GCB as substitutions with an underscore (`_`) prefix. If the variable doesn't exist, the substitution will exist but be empty.
    48  - `--build-dir`: If provided, this directory will be uploaded as the source for the Google Cloud Build run.
    49  - `--gcb-config`: If provided, this will be used as the name of the Google Cloud Build config file.
    50  - `--no-source`: If true, no source will be uploaded with this build.
    51  - `--with-git-dir`: If true, upload the .git directory to GCB, so we can e.g. get the git log and tag.
    52  
    53  ### A note about logging in Prow
    54  
    55  Prow job logs can be viewed at a URI constructed as follows:
    56  `https://prow.k8s.io/view/gs/kubernetes-jenkins/logs/<job-name>/<job-number>` e.g.,
    57  https://prow.k8s.io/view/gs/kubernetes-jenkins/logs/ci-kubernetes-prototype-build/1187171788975509509
    58  
    59  When `--log-dir` is specified (which is the default case when running in Prow),
    60  the GCB build logs will be written to a set of log files, based on the variant(s).
    61  
    62  For example:
    63  - No variant --> `build.log` (https://storage.googleapis.com/kubernetes-jenkins/logs/post-release-push-image-k8s-cloud-builder/1186437931728900096/artifacts/build.log)
    64  - Variant: `build-ci` --> `build-ci.log` (https://storage.googleapis.com/kubernetes-jenkins/logs/ci-kubernetes-prototype-build/1187156434249322500/artifacts/build-ci.log)
    65  
    66  For single-variant jobs where the preference is to log directly to stdout (so
    67  that the log is instead visible in `https://prow.k8s.io/view/gs/kubernetes-jenkins/logs/<job-name>/<job-number>`),
    68  `LOG_TO_STDOUT="y"` can be specified.