Installing on Google Cloud VM

This page describes how to install Piped on Google Cloud VM.

Prerequisites

Having piped’s ID and Key strings
  • Ensure that the piped has been registered and you are having its PIPED_ID and PIPED_KEY strings.
  • If you are not having them, this page guides you how to register a new one.
Preparing SSH key
  • If your Git repositories are private, piped requires a private SSH key to access those repositories.
  • Please checkout this documentation for how to generate a new SSH key pair. Then add the public key to your repositories. (If you are using GitHub, you can add it to Deploy Keys at the repository’s Settings page.)

Installation

  • Preparing a piped configuration file as the following:

    apiVersion: pipecd.dev/v1beta1
    kind: Piped
    spec:
      projectID: {PROJECT_ID}
      pipedID: {PIPED_ID}
      pipedKeyData: {BASE64_ENCODED_PIPED_KEY}
      # Write in a format like "host:443" because the communication is done via gRPC.
      apiAddress: {CONTROL_PLANE_API_ADDRESS}
    
      git:
        sshKeyData: {BASE64_ENCODED_PRIVATE_SSH_KEY}
    
      repositories:
        - repoId: {REPO_ID_OR_NAME}
          remote: git@github.com:{GIT_ORG}/{GIT_REPO}.git
          branch: {GIT_BRANCH}
    
      # Optional
      # Uncomment this if you want to enable this Piped to handle Cloud Run application.
      # platformProviders:
      #  - name: cloudrun-in-project
      #    type: CLOUDRUN
      #    config:
      #      project: {GCP_PROJECT_ID}
      #      region: {GCP_PROJECT_REGION}
    
      # Optional
      # Uncomment this if you want to enable this Piped to handle Terraform application.
      #  - name: terraform-gcp
      #    type: TERRAFORM
    
      # Optional
      # Uncomment this if you want to enable SecretManagement feature.
      # https://pipecd.dev//docs/user-guide/managing-application/secret-management/
      # secretManagement:
      #   type: KEY_PAIR
      #   config:
      #     privateKeyData: {BASE64_ENCODED_PRIVATE_KEY}
      #     publicKeyData: {BASE64_ENCODED_PUBLIC_KEY}
    

See ConfigurationReference for the full configuration.

  • Creating a new secret in SecretManager to store above configuration data securely

    gcloud secrets create vm-piped-config --data-file={PATH_TO_CONFIG_FILE}
    
  • Creating a new Service Account for Piped and giving it needed roles

    gcloud iam service-accounts create vm-piped \
      --description="Using by Piped running on Google Cloud VM" \
      --display-name="vm-piped"
    
    # Allow Piped to access the created secret.
    gcloud secrets add-iam-policy-binding vm-piped-config \
      --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/secretmanager.secretAccessor"
    
    # Allow Piped to write its log messages to Google Cloud Logging service.
    gcloud projects add-iam-policy-binding {GCP_PROJECT_ID} \
      --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
      --role="roles/logging.logWriter"
    
    # Optional
    # If you want to use this Piped to handle Cloud Run application
    # run the following command to give it the needed roles.
    # https://cloud.google.com/run/docs/reference/iam/roles#additional-configuration
    #
    # gcloud projects add-iam-policy-binding {GCP_PROJECT_ID} \
    #   --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
    #   --role="roles/run.developer"
    #
    # gcloud iam service-accounts add-iam-policy-binding {GCP_PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
    #   --member="serviceAccount:vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com" \
    #   --role="roles/iam.serviceAccountUser"
    
  • Running Piped on a Google Cloud VM

    # Enable remote-upgrade feature of Piped.
    # https://pipecd.dev/docs/user-guide/managing-piped/remote-upgrade-remote-config/#remote-upgrade
    # This allows upgrading Piped to a new version from the web console.
    
      gcloud compute instances create-with-container vm-piped \
        --container-image="ghcr.io/pipe-cd/launcher:v0.49.2" \
        --container-arg="launcher" \
        --container-arg="--config-from-gcp-secret=true" \
        --container-arg="--gcp-secret-id=projects/{GCP_PROJECT_ID}/secrets/vm-piped-config/versions/{SECRET_VERSION}" \
        --network="{VPC_NETWORK}" \
        --subnet="{VPC_SUBNET}" \
        --scopes="cloud-platform" \
        --service-account="vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com"
      
    
    # This just installs a Piped with the specified version.
    # Whenever you want to upgrade that Piped to a new version or update its config data you have to restart it.
    
      gcloud compute instances create-with-container vm-piped \
        --container-image="ghcr.io/pipe-cd/piped:v0.49.2" \
        --container-arg="piped" \
        --container-arg="--config-gcp-secret=projects/{GCP_PROJECT_ID}/secrets/vm-piped-config/versions/{SECRET_VERSION}" \
        --network="{VPC_NETWORK}" \
        --subnet="{VPC_SUBNET}" \
        --scopes="cloud-platform" \
        --service-account="vm-piped@{GCP_PROJECT_ID}.iam.gserviceaccount.com"
      
    

After that, you can see on PipeCD web at Settings page that Piped is connecting to the Control Plane. You can also view Piped log as described here.