sap-jenkins-library/resources/metadata/kubernetesDeploy.yaml

metadata:
  name: kubernetesDeploy
  aliases:
    - name: deployToKubernetes
      deprecated: true
  description: Deployment to Kubernetes test or production namespace within the specified Kubernetes cluster.
  longDescription: |-
    Deployment to Kubernetes test or production namespace within the specified Kubernetes cluster.

    !!! note "Deployment supports multiple deployment tools"
        Currently the following are supported:

        * [Helm](https://helm.sh/) command line tool and [Helm Charts](https://docs.helm.sh/developing_charts/#charts).
        * [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) and `kubectl apply` command.

    ## Helm
    Following helm command will be executed by default:

    ```
    helm upgrade <deploymentName> <chartPath> --install --force --namespace <namespace> --wait --timeout <helmDeployWaitSeconds> --set "image.repository=<yourRegistry>/<yourImageName>,image.tag=<yourImageTag>,secret.dockerconfigjson=<dockerSecret>,ingress.hosts[0]=<ingressHosts[0]>,,ingress.hosts[1]=<ingressHosts[1]>,...
    ```

    * `yourRegistry` will be retrieved from `containerRegistryUrl`
    * `yourImageName`, `yourImageTag` will be retrieved from `image`
    * `dockerSecret` will be calculated with a call to `kubectl create secret generic <containerRegistrySecret> --from-file=.dockerconfigjson=<dockerConfigJson> --type=kubernetes.io/dockerconfigjson --insecure-skip-tls-verify=true --dry-run=client --output=json`    
spec:
  inputs:
    secrets:
      - name: kubeConfigFileCredentialsId
        description: Jenkins 'Secret file' credentials ID containing kubeconfig file. Details can be found in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/).
        aliases:
          - name: kubeCredentialsId
            deprecated: true
        type: jenkins
      - name: kubeTokenCredentialsId
        description: Jenkins 'Secret text' credentials ID containing token to authenticate to Kubernetes. This is an alternative way to using a kubeconfig file. Details can be found in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/).
        aliases:
          - name: k8sTokenCredentialsId
            deprecated: true
        type: jenkins
      - name: dockerCredentialsId
        type: jenkins
      - name: dockerConfigJsonCredentialsId
        description: Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)).
        type: jenkins
      - name: githubTokenCredentialsId
        description: Jenkins credentials ID containing the github token.
        type: jenkins
    resources:
      - name: deployDescriptor
        type: stash
      - name: downloadedArtifact
        type: stash
    params:
      - name: additionalParameters
        aliases:
          - name: helmDeploymentParameters
        type: "[]string"
        description: Defines additional parameters for "helm install" or "kubectl apply" command.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: apiServer
        aliases:
          - name: k8sAPIServer
        type: string
        description: Defines the Url of the API Server of the Kubernetes cluster.
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: appTemplate
        aliases:
          - name: k8sAppTemplate
        type: string
        description: Defines the filename for the kubernetes app template (e.g. k8s_apptemplate.yaml).
        longDescription: |
          There are two supported ways for the template rendering:

          1. For a deployments using single image, you can use a placeholder `<image-name>`, which will be replaced with the image GUN.
          ```
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: app
            labels:
              app: app
          spec:
            replicas: 3
            selector:
              matchLabels:
                app: app
            template:
              metadata:
                labels:
                  app: app
              spec:
                containers:
                - name: app
                  image: <image-name>
          ```

          2. Helm styled templates, with the support for multi-image deployments.

          ```
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: app
            labels:
              app: app
          spec:
            replicas: 3
            selector:
              matchLabels:
                app: app
            template:
              metadata:
                labels:
                  app: app
              spec:
                containers:
                - name: app-1
                  image: "{{ .Values.image.repository}}:{{ .Values.image.tag }}"
                - name: app-2
                  image: "{{ .Values.image.app_2.repository}}:{{ .Values.image.app_2.tag }}"
          ```          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: chartPath
        aliases:
          - name: helmChartPath
        type: string
        description: Defines the chart path for deployments using helm. It is a mandatory parameter when `deployTool:helm` or `deployTool:helm3`.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        resourceRef:
          - name: commonPipelineEnvironment
            param: custom/localHelmChartPath
      - name: containerRegistryPassword
        description: Password for container registry access - typically provided by the CI/CD environment.
        type: string
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: dockerCredentialsId
            type: secret
            param: password
          - name: commonPipelineEnvironment
            param: container/repositoryPassword
          - name: commonPipelineEnvironment
            param: custom/repositoryPassword
      - name: containerImageName
        aliases:
          - name: dockerImageName
        type: string
        description: Name of the container which will be built - will be used together with `containerImageTag` instead of parameter `containerImage`
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: containerImageTag
        aliases:
          - name: artifactVersion
        type: string
        description: Tag of the container which will be built - will be used together with `containerImageName` instead of parameter `containerImage`
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        resourceRef:
          - name: commonPipelineEnvironment
            param: artifactVersion
      - name: containerRegistryUrl
        aliases:
          - name: dockerRegistryUrl
        type: string
        description: http(s) url of the Container registry where the image to deploy is located.
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/registryUrl
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        mandatory: true
      - name: containerRegistryUser
        description: Username for container registry access - typically provided by the CI/CD environment.
        type: string
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: dockerCredentialsId
            type: secret
            param: username
          - name: commonPipelineEnvironment
            param: container/repositoryUsername
          - name: commonPipelineEnvironment
            param: custom/repositoryUsername
      - name: containerRegistrySecret
        description: Name of the container registry secret used for pulling containers from the registry.
        longDescription: |-
          Name of the container registry secret used for pulling containers from the registry.

          **For `deployTool: helm/helm3`:**<br />
          If `containerRegistryUser` and `containerRegistryPassword` are provided, a secret is created on the fly and the information is passed to the helm template.<br />

          **For `deployTool: kubectl`:**<br />
          If `containerRegistryUser` and `containerRegistryPassword` are provided, a secret with the given name will be created in the Kubernetes cluster.

          If neither `containerRegistryUser` nor `containerRegistryPassword` are provided, it is expected that a secret with the configured name exists in the target Kubernetes cluster.<br />          
        type: string
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: regsecret
      - name: createDockerRegistrySecret
        type: bool
        description: "Only for `deployTool:kubectl`: Toggle to turn on `containerRegistrySecret` creation."
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: false
      - name: deploymentName
        aliases:
          - name: helmDeploymentName
        type: string
        description: Defines the name of the deployment. It is a mandatory parameter when `deployTool:helm` or `deployTool:helm3`.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: deployTool
        type: string
        description: Defines the tool which should be used for deployment.
        mandatory: true
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: kubectl
        possibleValues:
          - kubectl
          - helm
          - helm3
      - name: forceUpdates
        aliases:
          - name: force
        type: bool
        description: "Adds `--force` flag to a helm resource update command or to a kubectl replace command"
        mandatory: false
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: true
      - name: helmDeployWaitSeconds
        type: int
        description: Number of seconds before helm deploy returns.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: 300
      - name: helmValues
        type: "[]string"
        description: List of helm values as YAML file reference or URL (as per helm parameter description for `-f` / `--values`)
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: valuesMapping
        type: "map[string]interface{}"
        longDescription: |
          Mapping of values provided by Piper onto custom paths in format `[custom-path]: [piper-value]`

          Example:
          ```yaml
          valuesMapping:
            subchart.image.tag:        image.debug.tag
            subchart.image.repository: image.debug.repository
            subchart.image.pullsecret: secret.dockerconfigjson
          ```          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: githubToken
        description: "GitHub personal access token as per
          https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line"
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        type: string
        secret: true
        aliases:
          - name: access_token
        resourceRef:
          - name: githubTokenCredentialsId
            type: secret
          - type: vaultSecret
            default: github
            name: githubVaultSecretName
      - name: image
        aliases:
          - name: deployImage
        type: string
        description: Full name of the image to be deployed.
        deprecationMessage: This parameter is deprecated, please use [containerImageName](#containerimagename) and [containerImageTag](#containerimagetag)
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageNameTag
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: imageNames
        type: "[]string"
        description: List of names of the images to be deployed.
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageNames
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: imageNameTags
        type: "[]string"
        description: List of full names (registry and tag) of the images to be deployed.
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageNameTags
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: imageDigests
        type: "[]string"
        description: List of image digests of the images to be deployed, in the format `sha256:<hash>`. If provided, image digests will be appended to the image tag, e.g. `<repository>/<name>:<tag>@<digest>`
        resourceRef:
          - name: commonPipelineEnvironment
            param: container/imageDigests
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: ingressHosts
        type: "[]string"
        description: (Deprecated) List of ingress hosts to be exposed via helm deployment.
        longDescription: |-
          **DEPRECATED**<br />
          List of ingress hosts to be exposed via helm deployment.<br />
          Host names are passed to helm template via ingress configuration.<br />
          This requires a modification to the default helm template, thus it is not recommended.

          Recommendation is to use custom values and pass them via parameter `helmValues`.<br />
          Since helm supports multiple files on top of the `values.yaml`, landscape-specific attributes can be passed via a specific file.          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: keepFailedDeployments
        type: bool
        description: Defines whether a failed deployment will be purged
        default: false
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: runHelmTests
        type: bool
        description: Defines whether or not to run helm tests against the recently deployed release
        default: false
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: showTestLogs
        type: bool
        description: Defines whether to print the pod logs after running helm tests
        default: false
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
      - name: kubeConfig
        type: string
        description: Defines the path to the "kubeconfig" file.
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: kubeConfigFileCredentialsId
            type: secret
          - type: vaultSecretFile
            name: kubeConfigFileVaultSecretName
            default: kube-config
      - name: kubeContext
        type: string
        description: Defines the context to use from the "kubeconfig" file.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: kubeToken
        type: string
        description: Contains the id_token used by kubectl for authentication. Consider using kubeConfig parameter instead.
        scope:
          - GENERAL
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        resourceRef:
          - name: kubeTokenCredentialsId
            type: secret
      - name: namespace
        aliases:
          - name: helmDeploymentNamespace
          - name: k8sDeploymentNamespace
        type: string
        description: Defines the target Kubernetes namespace for the deployment.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: default
      - name: tillerNamespace
        aliases:
          - name: helmTillerNamespace
        type: string
        description: Defines optional tiller namespace for deployments using helm.
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: dockerConfigJSON
        type: string
        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/).
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        secret: true
        default: '.pipeline/docker/config.json'
        resourceRef:
          - name: dockerConfigJsonCredentialsId
            type: secret
          - type: vaultSecretFile
            name: dockerConfigFileVaultSecretName
            default: docker-config
      - name: deployCommand
        type: string
        description: "Only for `deployTool: kubectl`: defines the command `apply` or `replace`. The default is `apply`."
        mandatory: false
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
        default: apply
        possibleValues:
          - apply
          - replace
      - name: setupScript
        type: string
        description: HTTP location of setup script
        longDescription: |
          For helm-based deploymens only!
          HTTP location of setup script.
          The script will be downloaded from a GitHub location using the `githubToken` and executed before the installation of the helm package.          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: verificationScript
        type: string
        description: HTTP location of verification script
        longDescription: |
          For helm-based deploymens only!
          HTTP location of verification script.
          The script will be downloaded from a GitHub location using the `githubToken` and executed after installation of the helm package.
          It can be used to verify if all required artifacts are ready before progressing with for example `helmTest` using the step option `runHelmTests: true`          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
      - name: teardownScript
        type: string
        description: HTTP location of teardown script
        longDescription: |
          For helm-based deploymens only!
          HTTP location of setup script.
          The script will be downloaded from a GitHub location using the `githubToken` and executed at the end of the step.
          This can for example be used in order to remove a temporary namespace which was created for the test.          
        scope:
          - PARAMETERS
          - STAGES
          - STEPS
  containers:
    - image: dtzar/helm-kubectl:3.9.0
      workingDir: /config
      options:
        - name: -u
          value: "0"
      conditions:
        - conditionRef: strings-equal
          params:
            - name: deployTool
              value: helm3
    - image: dtzar/helm-kubectl:2.17.0
      workingDir: /config
      options:
        - name: -u
          value: "0"
      conditions:
        - conditionRef: strings-equal
          params:
            - name: deployTool
              value: helm
    - image: dtzar/helm-kubectl:2.17.0
      workingDir: /config
      options:
        - name: -u
          value: "0"
      conditions:
        - conditionRef: strings-equal
          params:
            - name: deployTool
              value: kubectl