Skip to main content

Google Cloud Platform (GCP)

Knocknoc integrates with Google Cloud Platform to dynamically control network access via VPC Firewall Rules or Cloud Armor Security Policies. When a user authenticates with Knocknoc, the agent adds their IP address to the configured GCP resource. On logout or grant expiry, the IP is removed.

Two modes are available depending on what you are protecting:

  • VPC Firewall — manages source or destination IP ranges on a VPC firewall rule. Use this to control access to VMs and other VPC resources.
  • Cloud Armor — manages source IP ranges on a Cloud Armor security policy rule. Use this to control access to services behind a Google Cloud Load Balancer.

Which Mode Should I Use?

Protecting VMs or VPC resources directly: Use VPC Firewall. Knocknoc manages the source or destination IP ranges on an existing firewall rule.

Protecting services behind a Cloud Load Balancer: Use Cloud Armor. Knocknoc manages the source IP ranges on a rule within an existing Cloud Armor security policy.

Comparison

VPC Firewall Cloud Armor
What it controls VPC firewall rule source/destination ranges Cloud Armor security policy rule source ranges
Protects VMs, GKE nodes, other VPC resources Services behind Cloud Load Balancer
Supports direction Ingress and Egress Ingress only (source IPs)
GCP API Compute Engine Firewalls API Compute Engine Security Policies API
Requires agent Yes Yes

Authentication

The Knocknoc agent authenticates to the GCP Compute Engine API using one of two methods:

Option A: Service Account Key (JSON)

Use this when the agent runs outside GCP (e.g., on-premises, in another cloud provider, or on a local machine).

  1. Create a service account in your GCP project (see Create a Service Account)
  2. Generate a JSON key for the service account
  3. Paste the full JSON key into the Service Account Key field in the Knocknoc wizard

Option B: Application Default Credentials (ADC)

Use this when the agent runs on GCP (e.g., on a Compute Engine VM or GKE pod). No key needs to be pasted into Knocknoc — the agent uses the credentials attached to the compute environment automatically.

  1. Create a service account in your GCP project
  2. Grant it the required IAM roles (see IAM Permissions)
  3. Attach the service account to the VM or GKE workload running the Knocknoc agent
  4. Leave the Service Account Key field empty in the Knocknoc wizard

ADC with Workload Identity Federation is the recommended approach when running on GCP, as it avoids long-lived key material.

IAM Permissions

Grant the service account the minimum permissions required for your chosen mode. You can use a predefined role or create a custom role.

VPC Firewall Mode

The service account needs permission to read and update VPC firewall rules.

Predefined role (simplest):

  • roles/compute.securityAdmin — Compute Security Admin

Custom role (least privilege):

Create a custom role with only these permissions:

  • compute.firewalls.get
  • compute.firewalls.update

To create a custom role:

  1. In the GCP Console, navigate to IAM & Admin > Roles
  2. Click Create Role
  3. Name it (e.g., Knocknoc VPC Firewall)
  4. Add the permissions listed above
  5. Click Create

Cloud Armor Mode

The service account needs permission to read and update Cloud Armor security policy rules.

Predefined role (simplest):

  • roles/compute.securityAdmin — Compute Security Admin

Custom role (least privilege):

Create a custom role with only these permissions:

  • compute.securityPolicies.get
  • compute.securityPolicies.update

To create a custom role:

Follow the same steps as above, using the Cloud Armor permissions instead.

Assigning the Role

  1. In the GCP Console, navigate to IAM & Admin > IAM
  2. Click Grant Access
  3. In the New principals field, enter the service account email (e.g., knocknoc@my-project.iam.gserviceaccount.com)
  4. In the Role field, select the predefined or custom role
  5. Click Save

Setup: VPC Firewall Mode

In VPC Firewall mode, Knocknoc manages the source or destination IP ranges on an existing VPC firewall rule. When a user is granted access, their IP is added to the rule's range list. On revocation, the IP is removed.

Step 1 — Create a Service Account

  1. In the GCP Console, navigate to IAM & Admin > Service Accounts
  2. Click Create Service Account
  3. Name it (e.g., knocknoc-agent)
  4. Click Create and Continue
  5. Grant it the required role (see IAM Permissions — VPC Firewall Mode)
  6. Click Done

If using a Service Account Key (Option A):

  1. Click on the newly created service account
  2. Go to the Keys tab
  3. Click Add Key > Create new key > JSON
  4. Save the downloaded JSON file securely — you will paste its contents into Knocknoc

Step 2 — Create the VPC Firewall Rule

Create a firewall rule that Knocknoc will manage. This rule should start with a placeholder source range — Knocknoc will replace it with authenticated user IPs.

  1. In the GCP Console, navigate to VPC Network > Firewall
  2. Click Create Firewall Rule
  3. Configure the rule:
    • Name: Choose a descriptive name (e.g., knocknoc-allow-ssh). Note this name — you will enter it in the Knocknoc wizard.
    • Direction of traffic: Ingress or Egress (as appropriate for your use case)
    • Action on match: Allow (or Deny, depending on your policy design)
    • Source IP ranges (for Ingress) or Destination IP ranges (for Egress): Enter 198.51.100.0/32 as a placeholder. This is an RFC 5737 documentation address that is never routed on the internet. Knocknoc uses it as a safe placeholder when no authenticated users are present, because GCP does not allow empty source/destination ranges.
    • Protocols and ports: Configure as appropriate (e.g., TCP port 22 for SSH)
    • Target: Configure targets as appropriate (e.g., target tags, target service accounts)
  4. Click Create

Step 3 — Deploy Knocknoc Agent

Deploy the Knocknoc orchestration agent with network access to the GCP Compute Engine API (compute.googleapis.com).

If using ADC (Option B), ensure the agent runs on a GCP resource with the service account attached.

Step 4 — Create Knoc in Knocknoc

  1. Select the Cloud / SaaS Knoc type
  2. Choose Google Cloud Platform as the Vendor

Step 5 — Configure Backend

Field Description
GCP Project ID Your GCP project ID (e.g., my-project-123456). Find this in the GCP Console dashboard or project selector.
Service Account Key (JSON) Paste the full contents of the JSON key file from Step 1. Leave empty if using ADC (Option B).

Step 6 — Configure ACL

Field Description
GCP Mode Select VPC Firewall Rule
Firewall Rule Name The name of the firewall rule created in Step 2 (e.g., knocknoc-allow-ssh). Must match exactly.
Direction Ingress or Egress — must match the direction configured on the firewall rule. Ingress manages source IP ranges; Egress manages destination IP ranges.

Step 7 — Assign Users and Test

  1. Assign users and/or groups to the Knoc in Knocknoc
  2. Log in as a test user
  3. In the GCP Console, navigate to VPC Network > Firewall and click on your rule
  4. Verify the user's IP address appears in the source (or destination) IP ranges
  5. Verify network access is granted as expected
  6. On logout or grant expiry, the IP is removed from the rule

Setup: Cloud Armor Mode

In Cloud Armor mode, Knocknoc manages the source IP ranges on a rule within an existing Cloud Armor security policy. This is used to control access to services behind a Google Cloud Load Balancer.

Step 1 — Create a Service Account

Follow the same process as VPC Firewall — Step 1, granting the Cloud Armor IAM permissions instead (see IAM Permissions — Cloud Armor Mode).

Step 2 — Create Cloud Armor Security Policy and Rule

Create a Cloud Armor security policy with a rule that Knocknoc will manage.

Create the security policy (if you don't have one):

  1. In the GCP Console, navigate to Network Security > Cloud Armor
  2. Click Create Policy
  3. Name it (e.g., knocknoc-policy)
  4. Set the Default rule action to Deny (recommended — deny all traffic by default, then allow authenticated users)
  5. Attach it to your backend service(s)
  6. Click Create

Add a rule for Knocknoc to manage:

  1. Open the security policy
  2. Click Add Rule
  3. Configure the rule:
    • Mode: Basic mode
    • Match: Enter 198.51.100.0/32 as the source IP range placeholder (same RFC 5737 documentation address as above)
    • Action: Allow (or Deny, depending on your policy design)
    • Priority: Choose a priority number (e.g., 1000). Note this number — you will enter it in the Knocknoc wizard. Lower numbers have higher priority.
  4. Click Save

Note the security policy name and rule priority — you will need both in the Knocknoc wizard.

Step 3 — Deploy Knocknoc Agent

Deploy the Knocknoc orchestration agent with network access to the GCP Compute Engine API (compute.googleapis.com).

If using ADC (Option B), ensure the agent runs on a GCP resource with the service account attached.

Step 4 — Create Knoc in Knocknoc

  1. Select the Cloud / SaaS Knoc type
  2. Choose Google Cloud Platform as the Vendor

Step 5 — Configure Backend

Field Description
GCP Project ID Your GCP project ID (e.g., my-project-123456)
Service Account Key (JSON) Paste the full contents of the JSON key file from Step 1. Leave empty if using ADC.

Step 6 — Configure ACL

Field Description
GCP Mode Select Cloud Armor Security Policy
Security Policy Name The name of the Cloud Armor security policy (e.g., knocknoc-policy). Must match exactly.
Rule Priority The priority number of the rule within the security policy (e.g., 1000). Must match the rule you created in Step 2.
Action Allow or Deny — must match the action configured on the Cloud Armor rule.

Step 7 — Assign Users and Test

  1. Assign users and/or groups to the Knoc in Knocknoc
  2. Log in as a test user
  3. In the GCP Console, navigate to Network Security > Cloud Armor and open your security policy
  4. Click on the rule at the priority you configured
  5. Verify the user's IP address appears in the source IP ranges
  6. Verify access to the protected service is granted as expected
  7. On logout or grant expiry, the IP is removed from the rule

Troubleshooting

Agent Logs

If you are experiencing issues, the first step is checking the orchestration agent logs. Common problems include:

  • Authentication failed: The service account key may be invalid, expired, or the service account may have been deleted. If using ADC, verify the compute resource has the correct service account attached.
  • Permission denied: The service account lacks the required IAM permissions. See IAM Permissions.
  • Resource not found: The firewall rule name, security policy name, or project ID does not match what exists in GCP. Names are case-sensitive.
  • Network connectivity: The agent cannot reach the GCP API endpoint (compute.googleapis.com). Ensure outbound HTTPS (port 443) is not blocked.

Conflict Errors (Concurrent Modifications)

The agent automatically retries operations that fail due to GCP fingerprint conflicts (HTTP 409/412). These occur when another process modifies the same resource simultaneously. If retries are exhausted, check for other systems or users modifying the same firewall rule or security policy.

Placeholder IP Range

When all user IPs are removed from a rule (e.g., all grants have expired), Knocknoc sets the source/destination range to 198.51.100.0/32. This is an RFC 5737 documentation address that is never routed on the internet. It serves as a safe placeholder because GCP does not allow firewall rules or Cloud Armor rules to have empty IP range lists.

If you see 198.51.100.0/32 in your rule's IP ranges, this means no users currently have active grants — this is normal and expected.

VPC Firewall Rule Direction Mismatch

If grants appear to succeed in Knocknoc but network access is not being granted, verify that the Direction setting in the Knocknoc ACL configuration matches the direction of the GCP firewall rule:

  • Ingress rules: Knocknoc manages the source IP ranges
  • Egress rules: Knocknoc manages the destination IP ranges

If these are mismatched, Knocknoc will modify the wrong IP range field on the rule.

Cloud Armor Rule Priority Mismatch

If modifying a Cloud Armor policy but the wrong rule is being updated, verify that the Rule Priority in the Knocknoc ACL configuration matches the priority of the specific rule you want Knocknoc to manage. Cloud Armor policies can contain multiple rules at different priorities.

Error Codes

The Knocknoc orchestration agent reports structured error codes when GCP operations fail. These codes appear in agent logs and are surfaced to the Knocknoc server.

Error codes are formatted as (agent error #NNNNN) description in log output.

Connection and Authentication (203000–203049)

Code Description Common Causes
203000 Failed to connect to GCP API API is unreachable — check network connectivity and DNS resolution for compute.googleapis.com
203001 Authentication failed Invalid or expired service account key (HTTP 401), or ADC not configured
203002 Authorization failed (insufficient permissions) Service account lacks required IAM role — needs compute.firewalls.* or compute.securityPolicies.* permissions (HTTP 403)
203003 Connection timed out Network timeout reaching the GCP API (HTTP 408/504 or network-level timeout)

VPC Firewall Operations (203050–203099)

Code Description Common Causes
203050 Failed to get VPC firewall rule The GET request for the firewall rule failed — see underlying error code for cause
203051 Failed to update VPC firewall rule The PATCH request to update the firewall rule failed — see underlying error code for cause

Cloud Armor Operations (203100–203149)

Code Description Common Causes
203100 Failed to get Cloud Armor security policy rule The GET request for the security policy rule failed — see underlying error code for cause
203101 Failed to update Cloud Armor security policy rule The PATCH request to update the security policy rule failed — see underlying error code for cause

Retry and Resource Errors (203150–203199)

Code Description Common Causes
203150 Update failed after retries (fingerprint conflict) Concurrent modifications to the same resource caused repeated HTTP 409/412 conflicts — check for other systems or users modifying the resource
203151 Resource not found The firewall rule name, security policy name, or rule priority does not match any resource in the GCP project (HTTP 404)

GCP API HTTP Status Code Mapping

The agent maps GCP API HTTP status codes to the error codes above:

HTTP Status Meaning Mapped Error Code
401 Unauthorized 203001
403 Forbidden 203002
404 Not Found 203151
408 Request Timeout 203003
409 Conflict 203150 (after retry exhaustion)
412 Precondition Failed 203150 (after retry exhaustion)
504 Gateway Timeout 203003

GCP Documentation References

Back to top