Skip to content

Latest commit

 

History

History
321 lines (231 loc) · 14 KB

README.md

File metadata and controls

321 lines (231 loc) · 14 KB
Raw

deploy-cloud-functions

This action deploys your function source code to Cloud Functions and makes the URL available to later build steps via outputs.

This GitHub Action is declarative, meaning it will overwrite any values on an existing Cloud Function deployment. If you manually deployed a Cloud Function, you must specify all parameters in this action. Any unspecified values will be reverted to their default value (which is usually "null").

Prerequisites

This action requires:

  • Google Cloud credentials that are authorized to deploy a Cloud Function. See the Authorization section below for more information.

  • Enable the Cloud Functions API

  • This action runs using Node 16. If you are using self-hosted GitHub Actions runners, you must use runner version 2.285.0 or newer.

Usage

jobs:
  job_id:
    runs-on: ubuntu-latest
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: actions/checkout@v3

    - id: auth
      uses: google-github-actions/auth@v0
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: '[email protected]'

    - id: 'deploy'
      uses: 'google-github-actions/deploy-cloud-functions@v0'
      with:
        name: 'my-function'
        runtime: 'nodejs16'

    # Example of using the output
    - id: 'test'
      run: 'curl "${{ steps.deploy.outputs.url }}"'

Inputs

  • name: (Required) Name of the Cloud Function.

  • runtime: (Required) Runtime to use for the function. Possible options documented here.

  • entry_point: (Optional) Name of a function (as defined in source code) that will be executed. Defaults to the resource name suffix, if not specified.

  • memory_mb: (Optional) The amount of memory in MB available for a function. Defaults to '256' (256 MB). The value must be the number of megabytes without the unit suffix.

  • region: (Optional) Region in which the function should be deployed. Defaults to us-central1.

  • env_vars: (Optional) List of key-value pairs to set as environment variables in the format: KEY1=VALUE1,KEY2=VALUE2. All existing environment variables will be removed, even if this parameter is not passed.

  • env_vars_file: (Optional) Path to a local YAML file with definitions for all environment variables. An example env_vars_file can be found here. All existing environment variables will be removed, even if this parameter is not passed. If env_vars is also given, values in env_vars take precendence over these values.

  • labels: (Optional) List of key-value pairs to set as function labels in the form label1=VALUE1,label2=VALUE2. All existing labels will be removed, even if this parameter is not passed.

  • source_dir: (Optional) Source directory for the function. Defaults to current directory. The action does not follow symlinks to directories or files when generating the upload artifact.

  • project_id: (Optional) ID of the Google Cloud project. If provided, this will override the project configured in the environment.

  • description: (Optional) Description for the Cloud Function.

  • vpc_connector: (Optional) The VPC Access connector that the function can connect to.

  • vpc_connector_egress_settings: (Optional) The egress settings for the connector, controlling what traffic is diverted through it.

  • ingress_settings: (Optional) The ingress settings for the function, controlling what traffic can reach it.

  • secret_environment_variables: (Optional) List of key-value pairs to set as environment variables at runtime of the format KEY1=SECRET_VERSION_REF where SECRET_VERSION_REF is a full resource name of a Google Secret Manager secret of the format "projects/p/secrets/s/versions/v". If the version is omitted, it will default to "latest".

    For example, this mounts version 5 of the api-key secret into $API_KEY inside the function's runtime:

    secret_environment_variables: 'API_KEY=projects/my-project/secrets/api-key/versions/5'

    All existing secrets will be removed, even if this parameter is not passed.

  • secret_volumes: (Optional) List of key-value pairs to mount as volumes at runtime of the format "PATH=SECRET_VERSION_REF" where PATH is the mount path inside the container (e.g. "/etc/secrets/my-secret") and SECRET_VERSION_REF is a full resource name of a Google Secret Manager secret of the format "projects/p/secrets/s/versions/v". If the version is omitted, it will default to "latest".

    For example, this mounts the latest value of the api-key secret at /etc/secrets/api-key inside the function's filesystem:

    secret_volumes: '/etc/secrets/api-key=projects/my-project/secrets/api-key'

    All existing secret volume mounts will be removed, even if this parameter is not passed.

  • service_account_email: (Optional) The email address of the Google Cloud service account to use as the runtime service account for the function. If unspecified, the default Cloud Functions runtime service account is used.

    Note this differs from the service account used to deploy the Cloud Function, which is the currently-authenticated principal. See Authorization for more information.

  • timeout: (Optional) The function execution timeout in seconds. Defaults to 60.

  • min_instances: (Optional) The minimum number of instances for the function.

  • max_instances: (Optional) The maximum number of instances for the function.

  • https_trigger_security_level: (Optional) The security level for an HTTP(s)trigger. If set to "secure_always", the function will only be accessible over the https protocol. If set to "secure_optional", the function will be accessible over the http and https protocols. The default value is "security_level_unspecified", which uses the platform's default value. We recommend setting this value to "secure_always" unless you need your function to be accessible over a non-TLS connection.

  • event_trigger_type: (Optional) Specifies which action should trigger the function. Defaults to creation of http trigger.

  • event_trigger_resource: (Optional) Specifies which resource from eventTrigger is observed.

  • event_trigger_service: (Optional) The hostname of the service that should be observed.

  • event_trigger_retry: (Optional) If true, the event will be retried if the function returns a failure. The default value is false. Note this applies to function invocation from events, not the deployment itself.

  • deploy_timeout: (Optional) The function deployment timeout in seconds. Defaults to 300.

  • build_worker_pool: (Optional) Name of the Cloud Build Custom Worker Pool that should be used to build the function. The format of this field is projects/p/locations/l/workerPools/w.

  • build_environment_variables: (Optional) List of environment variables that should be available while the function is built. Note this is different than runtime environment variables, which should be set with 'env_vars'.

  • build_environment_variables_file: (Optional) Path to a local YAML file containing variables. See 'env_vars_file' for syntax.

  • docker_repository: (Optional) User managed repository created in Artifact Registry optionally with a customer managed encryption key. If specified, deployments will use Artifact Registry and must be of the format projects/p/locations/l/repositories/r. If unspecified and the deployment is eligible to use Artifact Registry, GCF will create and use a repository named 'gcf-artifacts' for every deployed region. This is the repository to which the function docker image will be pushed after it is built by Cloud Build. For more information, please see the documentation.

  • kms_key_name: (Optional) Resource name of a Google Cloud KMS crypto key used to encrypt/decrypt function resources of the format projects/p/locations/l/keyRings/r/cryptoKeys/k. If specified, you must also provide an artifact registry repository using the docker_repository field that was created with the same key.

  • credentials: (Deprecated) This input is deprecated. See auth section for more details. Service account key to use for authentication. This should be the JSON formatted private key which can be exported from the Cloud Console. The value can be raw or base64-encoded.

Allow unauthenticated requests

A Cloud Functions product recommendation is that CI/CD systems not set or change settings for allowing unauthenticated invocations. New deployments are automatically private services, while deploying a revision of a public (unauthenticated) service will preserve the IAM setting of public (unauthenticated). For more information, see Controlling access on an individual service.

Outputs

  • url: The URL of your Cloud Function. Only available with HTTP Trigger.

  • id: The full resource name of the function (e.g. projects/my-project/locations/my-location/functions/my-function.)

  • status: The status of the function (e.g. ACTIVE)

  • version: The version of the function (e.g. 1)

  • runtime: The chosen runtime (e.g. nodejs16)

Authorization

The deployment service account must have the following IAM permissions:

  • Cloud Functions Admin (roles/cloudfunctions.admin)

Additionally, the deployment service account must have permissions to act as (impersonate) the runtime service account, which can be achieved by granting the deployment service account "roles/iam.serviceAccountUser" permissions on the runtime service account. If unspecified, the runtime service account is the App Engine Default Service Account [email protected].

In some cases, the Cloud Build service account, which defaults as [email protected], may also need to be granted "roles/iam.serviceAccountUser" permission on the runtime service account.

See the Google Cloud documentation to learn more about custom runtime service accounts and additional configuration for deployment

Via google-github-actions/auth

Use google-github-actions/auth to authenticate the action. You can use Workload Identity Federation or traditional Service Account Key JSON authentication. by specifying the credentials input. This Action supports both the recommended Workload Identity Federation based authentication and the traditional Service Account Key JSON based auth.

See usage for more details.

Authenticating via Workload Identity Federation

jobs:
  job_id:
    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
    - uses: 'actions/checkout@v3'

    - id: 'auth'
      uses: 'google-github-actions/auth@v0'
      with:
        workload_identity_provider: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider'
        service_account: '[email protected]'

    - id: 'deploy'
      uses: 'google-github-actions/deploy-cloud-functions@v0'
      with:
        name: 'my-function'
        runtime: 'nodejs16'

Authenticating via Service Account Key JSON

jobs:
  job_id:
    steps:
    - uses: 'actions/checkout@v3'

    - id: 'auth'
      uses: 'google-github-actions/auth@v0'
      with:
        credentials_json: '${{ secrets.gcp_credentials }}'

    - id: 'deploy'
      uses: 'google-github-actions/deploy-cloud-functions@v0'
      with:
        name: 'my-function'
        runtime: 'nodejs16'

Via Application Default Credentials

If you are hosting your own runners, and those runners are on Google Cloud, you can leverage the Application Default Credentials of the instance. This will authenticate requests as the service account attached to the instance. This only works using a custom runner hosted on GCP.

jobs:
  job_id:
    steps:
    - uses: 'actions/checkout@v3'

    - id: 'deploy'
      uses: 'google-github-actions/deploy-cloud-functions@v0'
      with:
        name: 'my-function'
        runtime: 'nodejs16'

The action will automatically detect and use the Application Default Credentials.