Install and Configure Admission Controller

Install and configure the Sysdig Admission Controller to enforce security policies at deployment time.

Prerequisites

  • Cluster Shield version 1.13.0 or higher.

  • Sysdig Secure SaaS

  • Sysdig Shield installed. See Install Shield on Kubernetes.

  • Ensure Admission Controller is enabled for your account. If it isn’t, contact Sysdig Support.

Installation

The Admission Controller is installed as part of the Sysdig Shield deployment. To enable Admission Controller, deploy or upgrade the shield Helm chart with the following parameters:

helm upgrade --install --atomic --create-namespace \
  --namespace sysdig \
  --set cluster_config.name=ac-cluster \
  --set sysdig_endpoint.region=<SaaS Region Code> \
  --set sysdig_endpoint.access_key=<your-access-key> \
  --set features.admission_control.enabled=true \
  --set features.admission_control.container_vulnerability_management.enabled=true \
  --set features.admission_control.posture.enabled=true \
  shield sysdig/shield

By default, the Admission Controller is installed with dry_run: true. This means no workloads will be blocked immediately after installation. Policy violations are only logged, not enforced.

Verification

After deployment, confirm the Admission Controller is correctly installed and the webhooks are registered:

kubectl get validatingwebhookconfigurations | grep shield

Look for a webhook configuration named shield-cluster-admission-control. For more detail:

kubectl describe validatingwebhookconfigurations shield-cluster-admission-control

The Sysdig Admission Controller should now be enabled and you can now configure policies and actions to block deployments using Vulnerability Policies or Posture Policies.

Advanced Configurations

Dry Run Mode

Dry Run is a mode in the Admission Controller that simulates policy evaluations without enforcing rejections. It allows users to preview the results of the Admission Controller without actually blocking workloads. This helps you verify that your Admission Controller and related Vulnerability Policies or Posture Policies work as expected before triggering Warning or Failure actions.

When To Use Dry Run

Use dry_run only in these cases:

  • You don’t have a non-prod environment, such as dev or stage, to test blocking policies.
  • You’re doing early-stage policy experimentation and want to gather data before enforcing.
  • You want to monitor new policies in production before turning on enforcement. This is sometimes referred to as “shadow enforcement”.
  • You want to validate custom controls or third-party controls in a live system without causing disruption.

When Not To Use Dry Run

  • Don’t use dry_run as a long-term substitute for environment-based policy promotion.
  • Don’t assume dry_run covers all policy behavior; some logic (e.g. ordering, dependencies) might not behave exactly the same.
  • Don’t rely on it to validate what would have been blocked unless the tooling explicitly shows that.

Dry Run Limitations

  • dry_run only simulates a real “rejection” flow. No workload is blocked and no webhook failed.
  • You cannot test the behavior of failure_policy settings with it.
  • You cannot dry-run only a subset of policies; it’s all-or-nothing unless scoped in config.

Best Practices

  • For policy testing, we recommend non-prod environments, such as dev or stage, with real enforcement.
  • Use dry_run in combination with logging to understand the impact of new policies before enforcing.

By default, the Admission Controller is installed with dry_run: true. This means no workloads will be blocked immediately after installation.

To disable Dry Run mode, pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: true

Vulnerability-only Configuration

Enable the Vulnerability-only configuration for the Admission Controller if you only want to check your deployments against the Vulnerability Admission Policies.

Ensure the individual cluster or resources are within the scope of the defined policies.

Pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: false

Posture-only Configuration

Enable the Posture-only configuration for the Admission Controller if you only want to check created resources against the Posture Admission Policies.

Ensure the clusters or resources are within the scope of the defined policy.

Pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: false
    posture:
      # Enable the posture feature on the admission control
      enabled: true

Exclude Namespaces

To exclude specific namespaces from evaluation, add them to the Admission Controller exclusion list. The controller will skip these namespaces entirely, even if your Vulnerability Policies or Posture Policies normally include them.

Pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Default: dry_run is true (no enforcement, only simulated)
    dry_run: true
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: ["kube-system", "sysdig", "example-app"]
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: true

Change the Failure Policy

The Sysdig Admission Controller supports the standard Kubernetes failurePolicy configuration, which determines how the API server handles errors from the Admission Controller.

Fail

With this configuration, if the Admission Controller encounters an error or is unreachable, the API server will reject the admission request. This is the default behavior, ensuring that no unverified or potentially unsafe objects are created.

Pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Fail
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: true

Ignore

With this configuration, if the admission controller encounters an error or is unreachable, the API server will allow the admission request to proceed. This can help avoid disruptions if the webhook is temporarily unavailable but may allow unverified objects.

Pass the following configuration settings to the shield chart:

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 10
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: true

For more details, see the Kubernetes documentation on failurePolicy.

Set the Request Timeout

Kubernetes API servers enforce a maximum timeout of 30 seconds for all admission webhook calls. If a webhook does not respond within this window, the API server treats the call as a timeout and applies the webhook’s failure_policy (Fail or Ignore) to determine whether to accept or reject the admission request.

Key Points:

  • The maximum value for timeout is 30 seconds.
  • If timeout is not set, the default is 10 seconds.
  • The API server will never wait longer than 30 seconds, even if a higher value is configured.
  • If the webhook does not respond in time, the API server applies the configured failure_policy in the Sysdig Shield chart.

To achieve this and increase your Validating Webhook timeouts the following configuration can be passed to the Sysdig Shield chart:

By configuring a longer timeout you may impact your deployment and kubectl command execution times if the Validating Webhook is not returned in a timely fashion.

features:
  admission_control:
    # Enable the admission control feature
    enabled: true
    # The policy to apply when a request is denied
    failure_policy: Ignore
    # Set dry_run to false to block non-compliant workloads
    dry_run: false
    # The timeout for the admission control feature
    timeout: 30
    # The port that will be used to expose admission control endpoints
    http_port: 8443
    # The list of namespaces that will be excluded from the admission control
    excluded_namespaces: []
    container_vulnerability_management:
      # Enable the container vulnerability management feature on the admission control
      enabled: true
    posture:
      # Enable the posture feature on the admission control
      enabled: true