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,authenticates, 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 areyou're protecting:

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

Which Mode Should I Use?

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

Protecting servicesServices 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: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 —Knocknoc; the agent usespicks theup credentials attached tofrom 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,GCP assince 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.one.

VPC Firewall Mode

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

Predefined role (simplest):

  • roles/compute.securityAdmin — (Compute Security AdminAdmin)

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, navigatego 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 AdminAdmin)

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,above usingwith the Cloud Armor permissions instead.

Assigning the Role

  1. In the GCP Console, navigatego to IAM & Admin > IAM
  2. Click Grant Access
  3. In the New principals field, enterEnter the service account email in New principals (e.g., knocknoc@my-project.iam.gserviceaccount.com)
  4. InSelect the Role field, select theyour predefined or custom role in 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 —1: Create a Service Account

  1. In the GCP Console, navigatego 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 —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 securelysecurely. — you willYou'll paste its contents into Knocknoc

Step 2 —2: Create the VPC Firewall Rule

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

  1. In the GCP Console, navigatego to VPC Network > Firewall
  2. Click Create Firewall Rule
  3. Configure the rule:
    • Name: Choose asomething descriptive name (e.g., knocknoc-allow-ssh). Note this namename, — you willyou'll 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): Enterenter 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,present because GCP does not allow empty source/destination ranges.
    • Protocols and ports: Configurewhatever asyou appropriateneed (e.g., TCP port 22 for SSH)
    • Target: Configureset your targets as appropriate (e.g., target tags, target service accounts)
  4. Click Create

Step 3 —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), ensuremake sure the agent runs on a GCP resource with the service account attached.

Step 4 —4: Create Knoc in Knocknoc

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

Step 5 —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 —6: Configure ACL

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

Step 7 —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, navigatego 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 grantedworks as expected
  6. On logout or grant expiry, the IP isshould be 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.policy, This is used to controlcontrolling access to services behind a Google Cloud Load Balancer.

Step 1 —1: Create a Service Account

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

Step 2 —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, navigatego 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 —recommended: deny all traffic by default, then allow authenticated users)users via Knocknoc)
  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: Enterenter 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: Choosepick a priority number (e.g., 1000). Note this numbernumber, — you willyou'll enter it in the Knocknoc wizard. Lower numbers have= higher priority.
  4. Click Save

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

Step 3 —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), ensuremake sure the agent runs on a GCP resource with the service account attached.

Step 4 —4: Create Knoc in Knocknoc

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

Step 5 —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 —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 infrom Step 2.
Action Allow or Deny. — mustMust match the action configured on the Cloud Armor rule.

Step 7 —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, navigatego 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 expectedworks
  7. On logout or grant expiry, the IP isshould be removed from the rule

Troubleshooting

Agent Logs

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

  • Authentication failed:failed: Thethe service account key may be invalid, expired, or the service account may have been deleted. If using ADC, verifycheck that the compute resource has the correct service account attached.
  • Permission denied:denied: Thethe service account lacksis the requiredmissing IAM permissions. See IAM Permissions.
  • Resource not found:found: Thethe firewall rule name, security policy name, or project ID does notdoesn't match what exists in GCP. Names are case-sensitive.
  • Network connectivity:connectivity: Thethe agent cannotcan't reach the GCP API endpoint (compute.googleapis.com). EnsureCheck that 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 occurhappen when another process modifies the same resource simultaneously.at the same time. 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 asIt's a safe placeholder because GCP does notdoesn't 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, thisit just means no users currently have active grantsgrants. — thisThis is normal and expected.normal.

VPC Firewall Rule Direction Mismatch

If grants appear to succeed in Knocknoc but network access isisn't notactually beingworking, granted, verifycheck that the Direction setting in the Knocknoc ACL configuration matches the direction ofon the GCP firewall rule:

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

If these aredon't mismatched,match, Knocknoc will modify the wrong IP range field on the rule.

Cloud Armor Rule Priority Mismatch

If modifyingthe awrong Cloud Armor policy but the wrong rule is being updated, verifycheck 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 containhave 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 surfacedforwarded to the Knocknoc server.

Error codes areshow formattedup as (agent error #NNNNN) description in log output.

Connection and Authentication (203000–203000-203049)

Code Description Common Causes
203000 Failed to connect to GCP API API isunreachable. unreachable — checkCheck 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 requiredmissing IAM rolerole. — needsNeeds 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–203050-203099)

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

Cloud Armor Operations (203100–203100-203149)

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

Retry and Resource Errors (203150–203150-203199)

Code Description Common Causes
203150 Update failed after retries (fingerprint conflict) Concurrent modifications to the same resource caused repeated HTTP 409/412 conflictsconflicts. — checkCheck for other systems or users modifying the resource
203151 Resource not found The firewallFirewall rule name, security policy name, or rule priority does notdoesn't 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:as follows:

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