github.com/ouraigua/jenkins-library@v0.0.0-20231028010029-fbeaf2f3aa9b/resources/metadata/kanikoExecute.yaml (about)

     1  metadata:
     2    name: kanikoExecute
     3    description: Executes a [Kaniko](https://github.com/GoogleContainerTools/kaniko) build for creating a Docker container.
     4    longDescription: |
     5      Executes a [Kaniko](https://github.com/GoogleContainerTools/kaniko) build for creating a Docker container.
     6  
     7      ### Building one container image
     8  
     9      For building one container image the step expects that one of the containerImage, containerImageName or --destination (via buildOptions) is set.
    10  
    11      ### Building multiple container images
    12  
    13      The step allows you to build multiple container images with one run.
    14      This is suitable in case you need to create multiple images for one microservice, e.g. for testing.
    15  
    16      All images will get the same "root" name and the same versioning.<br />
    17      **Thus, this is not suitable to be used for a monorepo approach!** For monorepos you need to use a build tool natively capable to take care for monorepos
    18      or implement a custom logic and for example execute this `kanikoExecute` step multiple times in your custom pipeline.
    19  
    20      You can activate multiple builds using the parameter [containerMultiImageBuild](#containermultiimagebuild)
    21  
    22      Behavior can be adapted using:
    23  
    24      * [containerMultiImageBuildExcludes](#containermultiimagebuildexcludes) for defining excludes
    25      * [containerMultiImageBuildTrimDir](#containermultiimagebuildtrimdir) for removing parent directory part from image name
    26  
    27      Examples:
    28  
    29      #### Multiple containers in sub directories
    30  
    31      Configuration as follows:
    32  
    33      ```
    34      general:
    35        containerImageName: myImage
    36      steps:
    37        kanikoExecute:
    38          containerMultiImageBuild: true
    39      ```
    40  
    41      Following Dockerfiles are available in the repository:
    42  
    43      * sub1/Dockerfile
    44      * sub2/Dockerfile
    45  
    46      Following final image names will be built:
    47  
    48      * `myImage-sub1`
    49      * `myImage-sub2`
    50  
    51      #### Multiple containers in sub directories while trimming a directory part
    52  
    53      Configuration as follows:
    54  
    55      ```
    56      general:
    57        containerImageName: myImage
    58      steps:
    59        kanikoExecute:
    60          containerMultiImageBuild: true
    61          containerMultiImageBuildTrimDir: .ci
    62      ```
    63  
    64      Following Dockerfiles are available in the repository:
    65  
    66      * .ci/sub1/Dockerfile
    67      * .ci/sub2/Dockerfile
    68  
    69      Following final image names will be built:
    70  
    71      * `myImage-sub1`
    72      * `myImage-sub2`
    73  
    74  spec:
    75    inputs:
    76      secrets:
    77        - name: dockerConfigJsonCredentialsId
    78          description: Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)). You can create it like explained in the [protocodeExecuteScan Prerequisites section](https://www.project-piper.io/steps/protecodeExecuteScan/#prerequisites).
    79          type: jenkins
    80      params:
    81        - name: buildOptions
    82          type: "[]string"
    83          description: Defines a list of build options for the [kaniko](https://github.com/GoogleContainerTools/kaniko) build.
    84          scope:
    85            - PARAMETERS
    86            - STAGES
    87            - STEPS
    88          default:
    89            - --skip-tls-verify-pull
    90            # fixing Kaniko issue https://github.com/GoogleContainerTools/kaniko/issues/1586
    91            # as per comment https://github.com/GoogleContainerTools/kaniko/issues/1586#issuecomment-945718536
    92            - --ignore-path=/workspace
    93            - --ignore-path=/busybox
    94        - name: buildSettingsInfo
    95          type: string
    96          description: Build settings info is typically filled by the step automatically to create information about the build settings that were used during the mta build. This information is typically used for compliance related processes.
    97          scope:
    98            - STEPS
    99            - STAGES
   100            - PARAMETERS
   101          resourceRef:
   102            - name: commonPipelineEnvironment
   103              param: custom/buildSettingsInfo
   104        - name: containerBuildOptions
   105          type: string
   106          description: Deprected, please use buildOptions. Defines the build options for the [kaniko](https://github.com/GoogleContainerTools/kaniko) build.
   107          scope:
   108            - PARAMETERS
   109            - STAGES
   110            - STEPS
   111        - name: containerImage
   112          aliases:
   113            - name: containerImageNameAndTag
   114              deprecated: true
   115          type: string
   116          description: Defines the full name of the Docker image to be created including registry, image name and tag like `my.docker.registry/path/myImageName:myTag`. If `containerImage` is not provided, then `containerImageName` or `--destination` (via buildOptions) should be provided.
   117          scope:
   118            - PARAMETERS
   119            - STAGES
   120            - STEPS
   121        - name: containerImageName
   122          aliases:
   123            - name: dockerImageName
   124          type: string
   125          description: Name of the container which will be built - will be used instead of parameter `containerImage`. If `containerImageName` is not provided, then `containerImage` or `--destination` (via buildOptions) should be provided.
   126          mandatoryIf:
   127            - name: containerMultiImageBuild
   128              value: true
   129          scope:
   130            - GENERAL
   131            - PARAMETERS
   132            - STAGES
   133            - STEPS
   134        - name: containerImageTag
   135          aliases:
   136            - name: artifactVersion
   137          type: string
   138          description: Tag of the container which will be built - will be used instead of parameter `containerImage`
   139          scope:
   140            - GENERAL
   141            - PARAMETERS
   142            - STAGES
   143            - STEPS
   144          resourceRef:
   145            - name: commonPipelineEnvironment
   146              param: artifactVersion
   147        - name: multipleImages
   148          aliases:
   149            - name: images
   150          type: "[]map[string]interface{}"
   151          description: |
   152            This parameter is only needed if `kanikoExecute` should create multiple images using the same root Dockerfile, but with different sub-contexts.
   153            Otherwise it can be ignored!!!
   154  
   155            In case of multiple images, this array contains one entry for each image.
   156            Either containerImageName OR containerImage MUST be provided for each entry.
   157            contextSubPath MUST be provided for each entry.
   158  
   159            Array keys:
   160              contextSubPath - Set a context subpath.
   161              dockerfilePath - Dockerfile path (optional). If empty, root will be used.
   162              containerImageName - Name of the container which will be built.
   163              containerImageTag - Tag of the container which will be built. If empty - root containerImageTag will be used.
   164              containerImage - Defines the full name of the Docker image to be created including registry.
   165  
   166            ```yaml
   167            containerRegistryUrl: docker.io
   168            containerImageTag: latest
   169            multipleImages:
   170            - containerImageName: myImage1
   171              containerImageTag: v1.0.0
   172              contextSubPath: path/to/folder
   173            ```
   174          scope:
   175            - PARAMETERS
   176            - STEPS
   177        - name: containerMultiImageBuild
   178          type: bool
   179          description: Defines if multiple containers should be build. Dockerfiles are used using the pattern **/Dockerfile*. Excludes can be defined via [`containerMultiImageBuildExcludes`](#containermultiimagebuildexscludes).
   180          scope:
   181            - GENERAL
   182            - PARAMETERS
   183            - STAGES
   184            - STEPS
   185        - name: containerMultiImageBuildExcludes
   186          type: '[]string'
   187          description: Defines a list of Dockerfile paths to exclude from the build when using [`containerMultiImageBuild`](#containermultiimagebuild).
   188          scope:
   189            - GENERAL
   190            - PARAMETERS
   191            - STAGES
   192            - STEPS
   193        - name: containerMultiImageBuildTrimDir
   194          type: 'string'
   195          description: Defines a trailing directory part which should not be considered in the final image name.
   196          scope:
   197            - PARAMETERS
   198            - STAGES
   199            - STEPS
   200        - name: containerPreparationCommand
   201          type: string
   202          description: Defines the command to prepare the Kaniko container. By default the contained credentials are removed in order to allow anonymous access to container registries.
   203          scope:
   204            - PARAMETERS
   205            - STAGES
   206            - STEPS
   207          default: rm -f /kaniko/.docker/config.json
   208        - name: containerRegistryUrl
   209          aliases:
   210            - name: dockerRegistryUrl
   211          type: string
   212          description: http(s) url of the Container registry where the image should be pushed to - will be used instead of parameter `containerImage`
   213          scope:
   214            - GENERAL
   215            - PARAMETERS
   216            - STAGES
   217            - STEPS
   218          resourceRef:
   219            - name: commonPipelineEnvironment
   220              param: container/registryUrl
   221        - name: containerRegistryUser
   222          aliases:
   223            - name: dockerRegistryUser
   224          type: string
   225          description: Username of the Container registry where the image should be pushed to - which will updated in a docker config json file. If a docker config json file is provided via parameter `dockerConfigJSON` , then the existing file will be enhanced
   226          scope:
   227            - GENERAL
   228            - PARAMETERS
   229            - STAGES
   230            - STEPS
   231          resourceRef:
   232            - name: commonPipelineEnvironment
   233              param: container/repositoryUsername
   234        - name: containerRegistryPassword
   235          aliases:
   236            - name: dockerRegistryPassword
   237          type: string
   238          description: Password of the Container registry where the image should be pushed to -  which will updated in a docker config json file. If a docker config json file is provided via parameter `dockerConfigJSON` , then the existing file will be enhanced
   239          scope:
   240            - GENERAL
   241            - PARAMETERS
   242            - STAGES
   243            - STEPS
   244          resourceRef:
   245            - name: commonPipelineEnvironment
   246              param: container/repositoryPassword
   247        - name: customTlsCertificateLinks
   248          type: "[]string"
   249          description: List containing download links of custom TLS certificates. This is required to ensure trusted connections to registries with custom certificates.
   250          scope:
   251            - PARAMETERS
   252            - STAGES
   253            - STEPS
   254        - name: dockerConfigJSON
   255          type: string
   256          description: Path to the file `.docker/config.json` - this is typically provided by your CI/CD system. You can find more details about the Docker credentials in the [Docker documentation](https://docs.docker.com/engine/reference/commandline/login/).
   257          scope:
   258            - PARAMETERS
   259            - STAGES
   260            - STEPS
   261          secret: true
   262          resourceRef:
   263            - name: dockerConfigJsonCredentialsId
   264              type: secret
   265            - type: vaultSecretFile
   266              name: dockerConfigFileVaultSecretName
   267              default: docker-config
   268        - name: dockerfilePath
   269          aliases:
   270            - name: dockerfile
   271          type: string
   272          description: Defines the location of the Dockerfile relative to the Jenkins workspace.
   273          scope:
   274            - PARAMETERS
   275            - STAGES
   276            - STEPS
   277          default: Dockerfile
   278        - name: targetArchitectures
   279          type: "[]string"
   280          description: Defines the target architectures for which the build should run using OS and architecture separated by a comma. (EXPERIMENTAL)
   281          default: []
   282          scope:
   283            - GENERAL
   284            - STEPS
   285            - STAGES
   286            - PARAMETERS
   287        - name: readImageDigest
   288          type: bool
   289          default: false
   290          scope:
   291            - STEPS
   292            - STAGES
   293            - PARAMETERS
   294        - name: createBOM
   295          type: bool
   296          description: Creates the bill of materials (BOM) using Syft and stores it in a file in CycloneDX 1.4 format.
   297          scope:
   298            - GENERAL
   299            - STEPS
   300            - STAGES
   301            - PARAMETERS
   302        - name: syftDownloadUrl
   303          type: string
   304          description: Specifies the download url of the Syft Linux amd64 tar binary file. This can be found at https://github.com/anchore/syft/releases/.
   305          scope:
   306            - PARAMETERS
   307            - STEPS
   308          default: "https://github.com/anchore/syft/releases/download/v0.62.3/syft_0.62.3_linux_amd64.tar.gz"
   309    outputs:
   310      resources:
   311        - name: commonPipelineEnvironment
   312          type: piperEnvironment
   313          params:
   314            - name: container/registryUrl
   315            - name: container/imageNameTag
   316            - name: container/imageDigest
   317            - name: container/imageNames
   318              type: "[]string"
   319            - name: container/imageNameTags
   320              type: "[]string"
   321            - name: container/imageDigests
   322              type: "[]string"
   323            - name: custom/buildSettingsInfo
   324        - name: reports
   325          type: reports
   326          params:
   327            - filePattern: "**/bom-*.xml"
   328              type: sbom
   329    containers:
   330      - image: gcr.io/kaniko-project/executor:debug
   331        command:
   332          - /busybox/tail -f /dev/null
   333        shell: /busybox/sh
   334        options:
   335          - name: -u
   336            value: "0"
   337          - name: --entrypoint
   338            value: ""
   339        env:
   340          - name: container
   341            value: docker