Policy Agent Installation

Install the policy agent.

    Policy Agent Function installation is done via Terraform scripts provided by Protegrity. Before running the template, some resources must be created manually.

    ESA Server

    Policy Agent function requires ESA server running and accessible from Agent Cloud Function on TCP port 8443. Make sure inbound connections on TCP:8443 are allowed for the network where ESA is hosted.

    Note down ESA IP address:

    ESA IP Address (EsaIpAddress): ___________________

    Certificates on ESA

    By default, ESA is configured with self-signed certificates, which can only be validated using self-signed CA certificate supplied in Cloud Function Environment variables configuration.

    In case ESA is configured with publicly signed certificates, this section can be skipped since the Cloud Function will use public CA to validate ESA certificates.

    To obtain self-signed CA certificate from ESA:

    1. Log in to ESA Web UI.

    2. Select Settings > Network > Manage Certificates.

    3. Hover over Server Certificate and click on download icon to download the CA certificate.

    4. After certificate is downloaded, open the PEM file in text editor and replace all new lines with escaped new line: \n.

      To escape new lines from command line, use one of the following commands depending on your operating system:

      Linux Bash:

      awk 'NF {printf "%s\\n",$0;}' ProtegrityCA.pem > output.txt

      Windows PowerShell:

      (Get-Content '.\ProtegrityCA.pem') -join '\n' | Set-Content 'output.txt'

    5. Record the certificate content with new lines escaped.

      ESA CA Server Certificate (EsaCaCert): ___________________

      This value will be used to set pty_esa_ca_server_cert Terraform variable in installation section.

    For more information about ESA certificate management refer to Certificate Management Guide in ESA documentation.

    Identify or Create a new VPC

    Google Cloud VPC is used to route traffic from Policy Agent Cloud Function to ESA. If your ESA is in a Google Cloud VPC, it is recommended to create a serverless VPC access and record its name:

    google_vpc_access_connector_name: ___________________

    If ESA is not on Google Cloud VPC, you can either create one or choose to let Terraform script to create one. The Terraform script will create the following elements:

    • NAT gateway

      To connect to ESA outside the Google Cloud Network

    • External IP address

      Can add it to the allowlist by the firewall in the network environment where ESA is hosted.

    • Serverless VPC access

      Allows connectivity from the Cloud function to the VPC.

    Creating ESA Credentials

    Policy Agent Function requires ESA credentials to be provided as one of the two options:

    Secret Manager

    Secret Manager is the recommended option for storing ESA credentials.

    Create ESA credentials secrets:

    1. Log in to Google Account and select project where Protegrity service will be installed.

    2. Go to Security > Secret Manager.

    3. Select CREATE SECRET.

    4. Specify the Secret Value:

      {
  "username": "{esa_username}", 
  "password": "{esa_password}"
}

    5. Select Create Secret.

    6. Once the secret is created, you should see the secret screen opened. If not click on the secret name to see a screen with secret versions.

    7. Click on Actions, next to the secret version you just created.

    8. Select Copy Resource ID and record the full secret version path, For example, projects/{project-id}/secrets/{secret name}/versions/2.

      Secret resource id: ___________________

    Custom Cloud Function

    If you have the skills to write code, you may provide a custom Cloud Function that returns the ESA credentials to the Policy Agent. One use case is when reading the ESA credentials from a third-party password vault.

    Create the Cloud Function:

    1. Create a new 2nd gen Cloud Function using any runtime.

      1. The Policy Agent does not provide an input payload.

      2. The Cloud Function must return a response according to the following schema:

        response: 
  type: object 
    properties: 
      username: string 
      password: string

        For example,

        example output: {"username": "admin", "password": "Password1234"}

      3. Sample GCP Function in Python:

        def handler(request): 
    return {"username": "admin", "password": "password1234"}

    2. Grant the Cloud Run Invoker role to the Policy Agent function service account.

    3. Grant the cloudfunctions.functions.get permission to the Policy Agent function service account role.

    4. Record the Function name:

      ESA CREDENTIALS FUNCTION NAME: _______________

    Install Policy Agent Function through Terraform Scripts

    Agent Terraform scripts provided by Protegrity create a Cloud Function in your Google account. If you don’t specify the deployment bucket Terraform parameter, a new storage bucket will also be created. You can also create the following optional resources by specifying the corresponding parameters:

    • Service account with IAM role
    • VPC with NAT external IP
    • VPC access connector

    To install Policy Agent Function through Terraform:

    1. From command shell, move to the directory where you downloaded Protegrity installation bundle.

    2. Unzip the bundle, then unzip the protegrity-agent-gcp-{version}.zip. Verify that the following files are available:

      • pty-agent-gcp/
      • main.tf
      • outputs.tf
      • README.md

    3. Open the main.tf file and update Terraform backend information at the top of the file:

      
terraform {
  backend "gcs" {
    bucket  = ""
    prefix  = "protegrity/terraform/pty-protect-gcp/state"
  }
}

    4. Set the bucket property to Terraform Backend Bucket Name recorded in Google Cloud Storage

    5. Set the prefix property with value unique to your deployment.

    6. In the same main.tf file, specify the following Terraform variables.

      ParameterDescription
      project_idThe Project ID recorded in the pre-configuration step
      regionThe Region recorded in the pre-configuration step, for example, us-central1.
      deployment_idSpecify short name to identify deployment. This id will be added to all resources deployed with Terraform.
      deployment_bucketUse Deployment Bucket Name recorded in pre-configuration or leave empty to create new bucket.
      deployment_bucket_locationGeographical location of deployment bucket, e.g., US, EU, ASIA.
      deployment_file_directory_pathPath to directory where deployment zip file is located. By default the deployment file should be in the same directory as this main.tf file.
      policy_download_cron_expressionCron expression determining how often policy agent function will run to synchronize security policy from ESA.
      create_service_accountLeave this as false if you created service account in pre-configuration. Otherwise set to true.
      agent_function_service_account_emailUse Agent Function Service account recorded in pre-configuration or leave empty.
      create_vpcSet this to true, if you would like to create VPC with NAT, external IP and vpc access connector, otherwise leave empty. This will be ignored if google_vpc_access_connector_name is specified.
      google_vpc_access_connector_nameSpecify the existing VPC access connector name you identified in earlier step, otherwise leave empty. This setting will disable create_vpc = true.
      google_vpc_access_connector_full_resource_nameAlternative configuration for VPC access connector. If this parameter is set the google_vpc_access_connector_name will be ignored. Use this parameter, if vpc connector is in different region/project that the one specified for the deployment.
      labelsYou can set this map to include labels for deployed resources. Pay attention to gcp label requirements. More information in: https://cloud.google.com/compute/docs/labeling-resources. For example, only use lowercase and maximum length of 63 characters.

      All the values were recorded in Pre-Configuration and this section’s previous steps.

    7. Provide Policy update Terraform variables. In the same main.tf file, you can specify configuration related to policy update. Any of these variables can be updated at any given time by running the terraform again or directly in the GCP Console. Most of the values were recorded in previous installation steps.

      Parameter

      Description

      Notes

      pty_esa_ip

      ESA IP address or hostname

      ESA Server

      pty_esa_ca_server_cert

      ESA self-signed CA certificate used by policy Agent Function to ensure ESA is the trusted server.

      Recorded in step Certificates on ESA

      In case ESA is configured with publicly signed certificates, the pty_esa_ca_server_cert configuration will be ignored.

      gcp_esa_credentials_secret_resource_id

      ESA username and password (encrypted value by Google Cloud Secrets Manager). For example, projects/{project-id}/secrets/{secret name}/versions/{version}

      Creating ESA Credentials

      pty_esa_credentials_function

      ESA credentials GCP function resource name. For example, projects/{project-name}/locations/{region}/functions/{esa-credentials-function-name}.

      Recorded in step Option 2: Custom Cloud Function ESA CREDENTIALS FUNCTION NAME. Presence of gcp_esa_credentials_secret_resource_id will cause this value to be ignored. The Policy Agent Function must have network access and IAM permissions to call the ESA Credentials function you have created in Option 2: Custom Cloud Function.

      gcp_kms_key_resource_name

      The Key full resource name. For Example, projects/{project-id}/locations/region/keyRings/ {key-ring}/cryptoKeys/{key-name}/cryptoKeyVersions/1

      Key Management Service

      gcp_protect_function_resource_name

      List of comma separated Protect function resource names. For Example, projects/{project-id}/ locations/{region}/functions/{function-name1},projects/{project-id}/ locations/{region}/functions/{function-name2}

      Use protect_function_resource_name recorded in Protect Service Installation section.

      gcp_policy_retention_storage_bucket

      Deployment Bucket Name where the encrypted policy will be written.

      You can use deployment bucket recorded in Google Cloud Storage section, or you can specify other existing bucket.

      gcp_policy_version_object_key

      Filename of the encrypted policy stored in the Deployment Bucket Name

      Default: policy.zip

      retain_policy_versions

      Number of policy versions to retain as backup. (e.g. 2 will retain the latest 2 policies and remove older ones). -1 retains all.

      Default: 10

      disable_deploy

      This flag can be either 1 or 0. If set to 1, then the agent will not update protector function with the newest policy. Else, the policy will be saved in the cloud storage bucket and deployed to the protector function.

      Default: 0

      log_level

      Application and audit logs verbiage level

      Default: INFO. Allowed values: DEBUG – the most verbose INFO, WARNING, ERROR – the least verbose

      policy_pull_timeout

      Time in seconds to wait for the ESA to send the full policy

      Default: 20

      pty_core_casesensitive

      Specifies whether policy usernames should be case sensitive

      Default: no. Allowed values: yes, no

      pty_core_emptystring

      Override default behavior. Empty string response values are returned as null values. For instance, (un)protect(’’) -> null (un)protect(’’) -> ''

      Default: empty. Allowed values: null, empty

      esa_connection_timeout

      Time in seconds to wait for the ESA response

      Default: 5s

      pty_addipaddressheader

      When enabled, agent will send its source IP address in the request header. This configuration works in conjunction with ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP (default=false). See Associating ESA Data Store With Cloud Protect Agent for more information.

      Default: yes. Allowed values: yes, no

      pty_datastore_key

      ESA policy datastore public key fingerprint (64 char long) e.g. 123bff642f621123d845f006c6bfff27737b21299e8a2ef6380aa642e76e89e5.

      The export key is the public part of an asymmetric key pair created in a Create KMS Key. A user with Security Officer permissions adds the public key to the data store in ESA via Policy Management > Data Stores > Export Keys. The fingerprint can then be copied using the Copy Fingerprint icon next to the key. Refer to Exporting Keys to Datastore for details.

      pty_sync_datastore

      Optional name of the policy datastore to sync with ESA. Refer to ESA documentation for more information on policy datastore sync.

      		Default: ""

    8. From local command line or Cloud Shell, change directory to location of the main.tf, for example:

      protegrity-agent-gcp-{version}/pty-agent-gcp/

    9. Run terraform init.

      Terraform will download necessary providers.

    10. Run terraform plan to verify configuration and print out deployment plan.

    11. Run terraform apply to deploy resources to your account. Once deployment is complete, Terraform will print output variables.

    12. Below is the sample output from successful deployment.

      
        Apply complete! Resources: 1 added, 0 changed, 0 destroyed. 
        Outputs: 
        agent_function_service_account_email = "pty-agent-test@test.iam.gserviceaccount.com" 
        deployment_bucket_name = "test-bucket" 
        nat_ip = 0 
        policy_agent_function_deployment_object = "pty-agent-test-1.0.1.zip" 
        policy_agent_function_name = "pty-agent-test"

    Test Agent Function Installation

    After configuration is complete, you can test the function.

    To test and run the Policy Agent Function:

    1. From the Google Cloud console, go to Cloud Run Functions or Cloud Run.

    2. Click on the function you just deployed: pty_agent_{deployment_id}.

    3. Click Test button at the top right section of the screen.

    4. Scroll down to CLI test command.

    5. Copy and run the curl command to trigger the agent. Alternatively, use the option Test in Cloud Shell.

    6. Wait for the function to complete.

    7. Navigate to the LOGS tab to view agent execution logs.

    8. Alternatively, you may review the logs by navigating to Logging from your Google Console. In the Log Explorer select the All resources dropdown, then Cloud Run Revision > pty-agent-{deployment-id} and apply.

      
Function execution took 23892 ms, finished with status: 'ok'
iap.policy_deployer:INFO:Deleting object [policy_v07-26-2021_21-00-00.zip]
iap.policy_deployer:INFO:Deleting object [policy_v07-26-2021_19-03-23.zip]
iap.policy_deployer:INFO:Removing old function versions in [test-artifacts]. Will retain [1] versions.
iap.policy_deployer:INFO:Updating function [projects/cloud-engineering-315519/locations/us-central1/functions/pty-protect-test] with new deployment artifact [test-artifacts/policy_v07-26-2021_21-00-01.zip] ...
iap.imp_creator:INFO:Uploading encrypted policy data to: [test-artifacts/policy_v07-26-2021_19-03-23.zip]
iap.imp_creator:INFO:Preparing deployment package ...
iap_agent_gcp.cloud_functions_util:INFO:Downloading function deployment package ...
iap.imp_creator:INFO:Encrypting policy package ...
iap.policy_agent:INFO:Preparing new policy deployment ...
iap.policy_agent:WARNING:Current policy deployment has no checksum_mapping metadata:
iap.imp_creator:INFO:Checking current policy version ...
iap.policy_agent:INFO:Current deployment package version: [policy_v07-26-2021_18-51-43.zip].
iap.policy_agent:INFO:Getting current policy metadata ...
iap.imp_creator:INFO:Policy downloaded successfully ...
iap.imp_creator:INFO:PepServer started ...
iap.imp_creator:INFO:Starting PepServer ...
iap.imp_creator:INFO:PepServer configured successfully
iap.imp_creator:INFO:Downloading certificates from ESA ...
iap.imp_creator:INFO:Configuring PepServer ...
iap.policy_agent:INFO:Starting policy agent ...
iap.policy_agent:INFO:Using Secret Manager [GCP_ESA_CREDENTIALS_SECRET_RESOURCE_ID] to retreive ESA credentials.
iap.policy_agent:INFO:PTY_CORE_CASESENSITIVE [no]
iap.policy_agent:INFO:PTY_CORE_EMPTYSTRING [empty]
iap.policy_agent:INFO:RETAIN_POLICY_VERSIONS [1]
iap.policy_agent:INFO:GCP_PROTECT_FUNCTION_RESOURCE_NAME [projects/test/locations/us-central1/functions/pty-protect-test]
iap.policy_agent:INFO:GCP_POLICY_VERSION_OBJECT_KEY [policy.zip]
iap.policy_agent:INFO:GCP_POLICY_RETENTION_STORAGE_BUCKET [test-artifacts]
iap.policy_agent:INFO:GCP_KMS_KEY_RESOURCE_NAME [projects/test/locations/us-central1/keyRings/test-key-ring/cryptoKeys/test-protect-asymmetric/cryptoKeyVersions/1]
iap.policy_agent:INFO:GCP_ESA_CREDENTIALS_SECRET_RESOURCE_ID [projects/1234/secrets/ESA_ADMIN_CREDENTIALS/versions/2]
iap.policy_agent:INFO:PTY_ESA_IP [54.236.107.39]
iap.policy_agent:INFO:POLICY_PULL_TIMEOUT [20]
iap.policy_agent:INFO:DISABLE_DEPLOY [0]
Function execution started

    Troubleshooting

    Configure additional logging:

    1. Set log_level Terraform variable on the Agent function to DEBUG.

    2. In the GCP Logs Explorer, you can run the query below, replacing placeholders with your deployment id and project name.

      resource.type="cloud_run_revision"
resource.labels.service_name=~"pty-agent-<deploymentd-id>"
severity=ERROR OR textPayload=~"\[error\]"
-logName="projects/<gcp-project-id>/logs/run.googleapis.com%2Frequests"

    3. Expand each log entry for more details. Check for jsonPayload > exception to see more detailed error.

    Error message

    Details

    iap_agent_gcp.cloud_functions_util.CloudFunctionsApiException: Resource 'projects/<account>/locations/<region>/functions/protegrity-protect-<deployment-id>' was not found
    		This error may indicate the following configuration issues:
    1. The function name indicated in setting gcp_protect_function_resource_name has been provided incorrectly, and thus cannot be found.
    2. disable_deploy has been set, and a dummy function has been entered to work around the gcp_protect_function_resource_name requirement. The Agent deployment requires a deployed Protect or Log Forwarder Cloud Run function to operate.
    [ERROR] policy_agent:Invalid GCP_PROTECT_FUNCTION_RESOURCE_NAME parameter value. Must be a comma separated list of Lambda Function names or ARNs.
    		This error may indicate the following configuration issues:
    1. The setting gcp_protect_function_resource_name is empty. The Agent deployment requires a deployed Protect or Log Forwarder Cloud Run function to operate, this setting may not be left empty.
    2. The list of function names provided to gcp_protect_function_resource_name contains invalid function name or is not valid csv format.
    [ERROR] iap_agent_gcp.cloud_functions_util:<HttpError 403 when requesting https://cloudfunctions.googleapis.com/v2/projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>:generateDo
wnloadUrl?alt=json returned "Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/<deployment-id>'". Details: "Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>'">
[ERROR] policy_agent:Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>'
...
iap_agent_gcp.cloud_functions_util.CloudFunctionsApiException: Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>'

    Indicates the Agent Cloud Run function’s identity does not have permissions to sourceCodeGet for Protect/Log Forwarder function(s) provided to the gcp_protect_function_resource_name configuration.


    Last modified : March 26, 2026