Skip to main content

Kubernetes based Collector

The JupiterOne Integration Operator is a Kubernetes-native solution for running JupiterOne integrations within your Kubernetes cluster. It manages Custom Resource Definitions (CRDs) for integration management and provides a scalable approach for organizations already using Kubernetes.

Prerequisites​

Cluster Requirements​

  • Kubernetes 1.16+
  • Helm 3+

JupiterOne Requirements​

  • Account ID — found at /settings/account-management
  • API Token — create one at /settings/account-api-tokens or /settings/api-tokens with the following permissions. If using a personal token (/settings/api-tokens), your user account must have these permissions assigned.
PermissionRequiredWhen
Collector Create/Read/Update/DeleteYesAlways
Shared: Graph Data Read/WriteYesAlways
Integration Create/Read/Update/DeleteNoOnly if creating Integrations via Helm
Permission screenshots

Set kubernetes collector permissions

Set kubernetes data graph permissions

Set kubernetes integration permissions

Installation​

tip

Can't reach GitHub from your cluster? Follow Private Registry Configuration instead.

Installation is handled by two helm charts

  1. Kubernetes Operator This chart installs the controllers that manage the CRDs. This chart can be upgraded independently of the Integration Runner.
  2. Integration Runner This chart installs a Custom Resource integrationrunner that tells the operator to create a new collector and register with JupiterOne.

Kubernetes Operator​

First, we need to install the operator which manages all the CRDs.

  1. Add the JupiterOne Helm Repository:

    helm repo add jupiterone https://jupiterone.github.io/helm-charts
    helm repo update

  2. Create a Namespace:

    kubectl create namespace jupiterone

  3. Install the Integration Operator:

    helm install integration-operator jupiterone/jupiterone-integration-operator --namespace jupiterone

Integration Runner​

To install the Integration runner, you need to provide your API token. You can choose from two options for managing the API token secret:

note

The runner will create a Collector with the same name.

This is the simplest method. The Helm chart will automatically create a Kubernetes Secret in the same namespace with your API token.

Parameters:

  • runnerName: The name of the Runner.
  • apiToken: Your API token. This will be created as a Secret in Kubernetes.
  • accountID: Your JupiterOne Account ID.
  • jupiterOneEnvironment (optional): The JupiterOne environment. This defaults to us. This can be found by inspecting the URL when accessing the UI such as <environment>.jupiterone.io.

Installation command:

helm install <runnerName> jupiterone/jupiterone-integration-runner --namespace jupiterone --set apiToken=<apiToken> --set accountID=<accountID>

Verification​

After installation, the runner should register with JupiterOne within 30 seconds.

kubectl get integrationrunner -n jupiterone

Expected output:

NAME     STATE     DETAIL   REGISTRATION   AGE
runner   running            registered     2m38s

Reading Secrets from AWS Secrets Manager​

By default, the runner API token and integration configuration are read from Kubernetes Secrets. If you run on AWS, you can instead source them from AWS Secrets Manager so that credentials never live in the cluster or in Git.

Two credentials support this:

  • Runner API token — set apiTokenSource on the IntegrationRunner.
  • Integration configuration — set secretSource on the IntegrationInstance.

Both are backward compatible with the existing secretAPITokenName / secretRef fields, which continue to reference Kubernetes Secrets. The new fields take precedence when both are set, so existing installations are unaffected.

Secret format​

The value stored in AWS Secrets Manager must be a JSON object.

  • For the API token, include a token key: 
    { "token": "<your-jupiterone-api-token>" }
  • For integration configuration, each key/value is merged into the integration config (overriding matching keys in config): 
    { "clientId": "abc", "clientSecret": "s3cret" }

Granting the operator access​

The operator loads AWS credentials from the default credential chain. On EKS, the recommended approach is IRSA: associate the operator's ServiceAccount with an IAM role by adding an annotation.

kubectl annotate serviceaccount -n jupiterone <operator-service-account> \
  eks.amazonaws.com/role-arn=arn:aws:iam::<account-id>:role/<role-name>

The role needs, at minimum, secretsmanager:GetSecretValue on the referenced secrets (and kms:Decrypt on the KMS key if the secret is encrypted with a customer-managed key):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:*:<account-id>:secret:jupiterone/*"
    }
  ]
}

Example: runner API token​

apiVersion: integrations.jupiterone.io/v1
kind: IntegrationRunner
metadata:
  name: runner
  namespace: jupiterone
spec:
  accountId: <account-id>
  syncIntervalSeconds: 30
  apiTokenSource:
    provider: awsSecretsManager
    awsSecretsManager:
      secretId: arn:aws:secretsmanager:us-east-1:123456789012:secret:jupiterone/api-token

Example: integration configuration​

apiVersion: integrations.jupiterone.io/v1
kind: IntegrationInstance
metadata:
  name: my-integration
  namespace: jupiterone
spec:
  collectorName: runner
  integrationDefinitionName: <integration>
  config:
    nonSensitiveValue: "example"
  secretSource:
    provider: awsSecretsManager
    awsSecretsManager:
      secretId: jupiterone/my-integration-creds

Fields​

Both apiTokenSource and secretSource share the same shape:

FieldRequiredDescription
providerYesawsSecretsManager or kubernetes.
awsSecretsManager.secretIdYes (for awsSecretsManager)ARN or name of the secret.
awsSecretsManager.regionNoAWS region of the secret. Defaults to the operator's region.
awsSecretsManager.versionStageNoVersion stage to retrieve. Defaults to AWSCURRENT.
kubernetes.nameYes (for kubernetes)Name of the Kubernetes Secret, in the same namespace.
note

Resolved values are cached in-memory to avoid calling AWS Secrets Manager on every reconcile. The cache duration is controlled by the operator's ASM_CACHE_TTL_SECONDS environment variable (default 60; set to 0 to disable caching).

note

For an IntegrationInstance, the resolved configuration is sent to JupiterOne when the integration instance is created, so it is also stored server-side. AWS Secrets Manager keeps the secret out of your cluster and Git; it is not end-to-end encryption.

Private Registry Configuration​

Use this when your cluster cannot pull images from ghcr.io (GitHub), for example because all images must be scanned and served from your own registry. Follow these steps instead of Installation.

note

Your cluster still needs outbound access to the JupiterOne API and to the systems each integration collects from. Images come from your registry; charts come from the .tgz files saved in step 1.

In the steps below, replace myregistry.example.com with your registry address. Do not include https://. The address can include a path, for example myregistry.example.com:5000/mirror; if it does, use only the host and port (myregistry.example.com:5000) for crane auth login and --docker-server.

Depending on your registry:

  • Private certificate authority: the machine that runs step 1 and every node must trust it. On macOS add it to the Keychain; on Linux use update-ca-certificates. On nodes, also restart containerd (or set ca in containerd's hosts.toml). The operator itself does not need it.
  • Harbor: create the project (the first part of the path, e.g. mirror) before step 1; otherwise crane copy fails with 401 Unauthorized. A project robot account with push and pull works for both steps.
  • Username with $ (e.g. a Harbor robot account robot$mirror+jupiterone): put it in single quotes, -u 'robot$mirror+jupiterone', or the shell drops part of it.

1. Copy and check the images and charts​

On a machine that can reach GitHub, with Helm, crane and cosign installed, open a terminal in an empty folder and log in to your registry:

read -rs PW   # type your registry password (not shown), then press Enter
echo "$PW" | crane auth login myregistry.example.com -u <username> --password-stdin   # host and port only

Then edit the first two lines and run the rest. It copies the Helm charts, the operator image and one image per integration you run, and checks each integration image:

REGISTRY=myregistry.example.com
INTEGRATIONS=(jira)        # chart names of the integrations you run, e.g. (jira wazuh)

# Charts, saved as .tgz files
helm pull jupiterone-integration-operator jupiterone-integration-runner "${INTEGRATIONS[@]}" \
  --repo https://jupiterone.github.io/helm-charts

# Operator image
OP=$(helm show chart ./jupiterone-integration-operator-*.tgz | awk '/^appVersion/{print $2}')
crane copy ghcr.io/jupiterone/jupiterone-integration-operator:${OP} \
  ${REGISTRY}/jupiterone/jupiterone-integration-operator:${OP}

# Integration images: copy each one, then check the copy is the one JupiterOne signed
for i in "${INTEGRATIONS[@]}"; do
  if crane copy ghcr.io/jupiterone/graph-${i}:latest ${REGISTRY}/jupiterone/graph-${i}:latest &&
    COSIGN_REPOSITORY=ghcr.io/jupiterone/graph-${i}-signatures \
      cosign verify ${REGISTRY}/jupiterone/graph-${i}:latest \
      --certificate-oidc-issuer https://token.actions.githubusercontent.com \
      --certificate-identity-regexp '^https://github\.com/JupiterOne/' > /dev/null; then
    echo "graph-${i} verified"
  else
    echo "graph-${i} FAILED"
  fi
done

Every integration must print graph-<name> verified. If anything prints an error or FAILED, stop and fix it before going on. A DENIED or UNAUTHORIZED error from ghcr.io means that integration's image is not public; contact JupiterOne support.

  • Keep the jupiterone/graph-<integration>:latest path unchanged. The operator only swaps ghcr.io for your registry.
  • The operator always runs :latest. Your copy never updates itself; to update an integration, copy its image again.
  • Set an integration up in the JupiterOne UI and don't know its image? Start a run after step 3, then run kubectl get integrationinstancejobs -n jupiterone -o 'custom-columns=NAME:.metadata.name,IMAGE:.spec.image'. For an image .../graph-X:latest, rerun the script in the same folder with INTEGRATIONS=(X). The run waits until the image is there.
  • graph-kubernetes is not covered here; use Kubernetes Managed.
warning

Copy images with crane copy, not docker pull/tag/push. Docker copies only one CPU architecture and changes the image, so the check above fails with no signatures found.

2. Create the namespace and registry secret​

kubectl create namespace jupiterone

kubectl create secret docker-registry my-registry-secret \
  --namespace jupiterone \
  --docker-server=myregistry.example.com \
  --docker-username=<username> \
  --docker-password=<password>

Using External Secrets or Sealed Secrets? Sync the secret into jupiterone as type kubernetes.io/dockerconfigjson (External Secrets: target.template.type: kubernetes.io/dockerconfigjson). An Opaque secret is ignored and pulls fail with no basic auth credentials.

3. Install the operator and runner​

# private-registry-values.yaml
controllerManager:
  container:
    image:
      repository: myregistry.example.com/jupiterone/jupiterone-integration-operator  # operator image
  imageRegistry: "myregistry.example.com"   # integration images
  imagePullSecrets:                         # registry login for the operator and every job
    - name: my-registry-secret
  disableImageSignatureCheck: true          # see "About the signature check" below
helm install integration-operator ./jupiterone-integration-operator-*.tgz \
  --namespace jupiterone \
  -f private-registry-values.yaml

helm install <runnerName> ./jupiterone-integration-runner-*.tgz \
  --namespace jupiterone \
  --set apiToken=<apiToken> \
  --set accountID=<accountID>

Outside the US, add --set jupiterOneEnvironment=<environment> (the <environment> in your <environment>.jupiterone.io URL). The runner takes the same options as in Integration Runner.

Then add integrations as described in Assigning an Integration. For the Helm option, install from the .tgz file and set collectorName to your <runnerName>. helm show values ./<integration>-*.tgz lists the integration's own settings. If an integration's docs say to run helm repo add or helm repo update, skip those.

helm install <integration> ./<integration>-*.tgz \
  --namespace jupiterone \
  --set collectorName=<runnerName> \
  -f <integration>-values.yaml               # the integration's own settings; leave out if none

4. Check it works​

kubectl get integrationrunner -n jupiterone   # REGISTRATION should show "registered"
kubectl get pods -n jupiterone \
  -o 'custom-columns=NAME:.metadata.name,IMAGE:.spec.containers[*].image'

Every image should start with myregistry.example.com. Integration job pods appear once an integration has run; to run one now, start it from the integration instance in the JupiterOne UI.

If kubectl get pods -n jupiterone shows ErrImagePull or ImagePullBackOff, the image is missing from your registry, the secret is wrong, or the nodes don't trust your registry's certificate (x509: certificate signed by unknown authority). kubectl describe pod <pod name> -n jupiterone shows the exact image it tried.

About the signature check​

Before each job, the operator can check the image's signature. With a private registry it ends up checking the image on ghcr.io, not your copy; the check in step 1 covers your copy.

The operator's check needs internet access to:

  • ghcr.io, where the signatures are published,
  • pkg-containers.githubusercontent.com, where ghcr.io serves its files from, and
  • tuf-repo-cdn.sigstore.dev, which provides the keys the check trusts.

If any of these is blocked, every job fails the check and never runs: no job pod appears, kubectl get integrationinstancejobs -n jupiterone shows PENDING or FAILED under VERIFIED (it keeps retrying), and the operator log shows Failed to verify image. That is why step 3 sets disableImageSignatureCheck: true. If all three are reachable, you can remove that line. You do not need to copy the signatures to your registry.

Resource Requests and Limits for Integration Jobs​

Many enterprise Kubernetes clusters enforce resource policies using Kyverno, OPA/Gatekeeper, or similar admission controllers. These policies often require all containers to declare CPU and memory requests and limits. By default, integration job containers created by the operator do not include resource requirements, which may cause job creation to be blocked by such policies.

Configuration​

Configure resource requests and limits for integration job containers using --set flags:

helm install integration-operator jupiterone/jupiterone-integration-operator \
  --namespace jupiterone \
  --set controllerManager.jobResources.requests.cpu=100m \
  --set controllerManager.jobResources.requests.memory=256Mi \
  --set controllerManager.jobResources.limits.cpu=1 \
  --set controllerManager.jobResources.limits.memory=1Gi

Or via a values file:

controllerManager:
  jobResources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 1Gi

When jobResources is not set, no resource requirements are applied to integration job containers (the default behavior).

Verifying​

After configuring job resources, trigger an integration run and inspect the created Job:

kubectl get jobs -n jupiterone -o yaml | grep -A 10 resources

Troubleshooting Job Creation Failures​

If integration jobs are not being created, check the IntegrationInstanceJob status:

kubectl get integrationinstancejobs -n jupiterone

The JobCreated column shows whether the Kubernetes Job was created. If it shows FAILED, inspect the full status for the error:

kubectl get integrationinstancejob <name> -n jupiterone -o jsonpath='{.status}'

Common causes:

  • Admission webhook rejection — configure jobResources to satisfy cluster resource policies.
  • Image pull failures — check imagePullSecrets configuration.

Labels, Annotations and Scheduling​

Many clusters require labels or annotations on every object, such as a team or cost-center label, or pin workloads to dedicated nodes. The charts support both.

Versions

These values need Integration Operator v0.6.0 or later (operator chart 1.6.0 or later) and runner chart 1.2.0 or later. Integration charts need a version that has them: kubernetes-managed 1.0.10 or later; for other integration charts, check that helm show values lists commonLabels. Upgrade the operator chart first. The runner and integration charts write new fields to the operator's CRDs. Against an older CRD, Helm 4 rejects the release (field not declared in schema). Helm 3 drops the fields silently, so only the chart's own objects get the labels.

Labels and annotations on every object​

Each chart has commonLabels and commonAnnotations. They are set on every object the chart creates, and on every object the operator creates for it:

ChartObjects
Integration OperatorEvery resource in the chart, including the CRDs and, with certmanager.enable, the metrics certificate Secret. The leader-election Lease gets the labels only. Also every object the operator creates for integration runs (see the next row).
Integration RunnerThe IntegrationRunner and its API token Secret (Chart-Assisted). Also every object the operator creates for this runner: its auth Secret, and for each run the run Secret, IntegrationInstanceJob, job Secret, Job and pod.
Integration charts, such as kubernetes-managedThe IntegrationInstance and its Secret. Also every object the operator creates for this integration's runs.

Set them in a values file:

commonLabels:
  team: security
  cost-center: "1234"
commonAnnotations:
  owner: platform@example.com

Pass the same values to each chart you install, or set different ones per chart. On the same key, the more specific chart wins: the integration chart's values override the runner's, and the runner's override the operator's.

  • Quote numbers. Helm reads 1234 as a number, not a string. Write "1234".
  • Keys the charts and the operator manage are skipped. The charts keep their own labels: app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/version, app.kubernetes.io/managed-by, helm.sh/chart and control-plane. Run objects never take log-watcher, job-name, controller-uid, batch.kubernetes.io/* or integrations.jupiterone.io/*. helm.sh/* and meta.helm.sh/* annotations are dropped everywhere.
  • Invalid entries. The operator drops an invalid key or value in a runner's labels, and logs it.
  • When changes apply. A helm upgrade updates the chart's own objects. Objects the operator creates pick up changes on the next integration run. Removing a key does not remove it from objects that already exist.
  • Not labelled. Kubernetes Events, the Secrets Helm uses to store releases, and objects Kubernetes creates on its own, such as the default ServiceAccount.

Integration job pods​

The operator chart's controllerManager.job values apply to every integration run:

ValueApplies to
labels, annotationsEvery object the operator creates for a run. They override commonLabels and commonAnnotations on the same key.
podLabels, podAnnotationsThe job pod.
nodeSelector, tolerations, affinityThe job pod's scheduling.
podSecurityContext, containerSecurityContextThe job pod's and container's security context.
controllerManager:
  job:
    podAnnotations:
      sidecar.istio.io/inject: "false"
    nodeSelector:
      pool: tools
    tolerations:
      - key: dedicated
        operator: Equal
        value: tools
        effect: NoSchedule

The operator checks these values when it starts. If a label is invalid, or the API server rejects a scheduling or security field, the new operator pod exits and the previous pod keeps running. Run kubectl rollout status deployment -n jupiterone after upgrading. Integration images run as root, so namespaces that enforce the restricted Pod Security Standard are not supported yet.

Integration charts have jobLabels, jobAnnotations, podLabels and podAnnotations for one integration's runs. They override the operator and runner values on the same key. Scheduling can only be set on the operator. If a key is invalid or managed by the operator, it is dropped and reported as an InvalidJobMetadata event on the IntegrationInstance:

kubectl get events -n jupiterone --field-selector reason=InvalidJobMetadata

The operator pod​

The operator's own Deployment and pod also have their own values. These override commonLabels and commonAnnotations on the same key.

controllerManager:
  deployment:
    labels: {}
    annotations: {}
  pod:
    labels: {}
    annotations: {}
  nodeSelector: {}
  tolerations: []
  affinity: {}

On tainted nodes, set controllerManager.tolerations for the operator pod as well as controllerManager.job.tolerations for the job pods.

Assigning an Integration​

Assigning an integration job to a collector first requires that there are collectors registered and available. Once collectors are available, the process for defining an integration job and assigning it to a collector is straightforward.

For integrations that are collector compatible, complete the integration configuration as normal. During configuration, you'll notice there's an additional option to choose where the integration should run.

Select Collector on the integration instance, and choose the corresponding collector for which you'd like the integration to run.

Choosing run on Collector within the JupiterOne integration instance configuration

Updating the Operator​

To update to the latest version:

helm repo update
helm upgrade integration-operator jupiterone/jupiterone-integration-operator --namespace jupiterone

Uninstalling​

To remove the operator:

helm uninstall <runnerName> --namespace jupiterone
helm uninstall integration-operator --namespace jupiterone
kubectl delete namespace jupiterone

Multiple Clusters​

Multiple Kubernetes clusters are supported by installing the JupiterOne Integration Operator and Integration Runner Helm charts on each cluster. Each cluster is managed independently by the operator running within that cluster.

To set up multiple clusters:

  • Repeat the installation steps for each cluster where you want to run collectors.
  • Each cluster will have its own Integration Runner and Integration(s) managed separately.

You may use automation tools such as ArgoCD, Flux, or other GitOps solutions to automate and manage Helm chart deployments across your clusters. This allows you to keep your collector deployments consistent and up to date in all environments.

note

Each collector is registered independently with JupiterOne, and integration jobs can be assigned to collectors in any cluster as needed.

ArgoCD​

You may use ArgoCD to automate Helm chart deployments in your clusters. The following are example ArgoCD Applications setting up the Integration Operator and Integration Runner.

note

You may find the current version of the Integration Operator and the Integration Runner by searching the helm repository.

helm repo update
helm repo search jupiterone

Integration Operator​

Replace <version> with the version you would like to install.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: jupiterone-integration-operator
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://jupiterone.github.io/helm-charts
    chart: jupiterone-integration-operator
    targetRevision: <version>
  destination:
    namespace: jupiterone
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Integration Runner​

Replace the <version>, <account-id> and <environment> with your own values.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: jupiterone-integration-runner
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://jupiterone.github.io/helm-charts
    chart: jupiterone-integration-runner
    targetRevision: <version>
    helm:
      values: |
        secretAPITokenName: j1token
        createSecret: false
        accountID: <account-id>
        jupiterOneEnvironment: <environment>
  destination:
    namespace: jupiterone
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Integration Instance​

You may also setup certain Integrations with Helm charts which are then supported in ArgoCD. Here is an example of setting up the Kubernetes Managed Integration. Replace <version> with the value from the latest chart.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kubernetes-managed
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://jupiterone.github.io/helm-charts
    chart: kubernetes-managed
    targetRevision: <version>
    helm:
      values: |
        collectorName: runner
        pollingInterval: ONE_WEEK
        ingestionSources:
          secrets: false
  destination:
    namespace: jupiterone
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Troubleshooting​

If pods are not starting or integrations are not running:

  • Check pod logs: kubectl logs -n jupiterone <pod-name>
  • Verify CRDs are present: kubectl get crd | grep jupiterone
  • Double-check authentication credentials
  • Ensure network connectivity to JupiterOne services

For integrations that assume an AWS IAM role (such as SBOM for AWS ECR), a job that starts and then fails with a Configuration failure usually means the job pod had no AWS credentials to assume the role. The spawned job pod has no AWS identity unless you give it one. On chart 1.4.0+ (operator v0.4.0+), set integration.jobServiceAccount.create=true with an eks.amazonaws.com/role-arn annotation so the chart provisions a dedicated, IRSA-annotated ServiceAccount for job pods. See the integration's installation guide for the trust-policy details.

If ingestion source settings from the chart do not take effect, check the IngestionSourcesApplied condition: kubectl get integrationinstance <name> -n jupiterone -o jsonpath='{.status.conditions[?(@.type=="IngestionSourcesApplied")]}'. On chart 1.5.0+ (operator v0.5.0+), the operator checks the value against the integration's ingestion sources and applies only the valid entries. Rejected lists the IDs that were not applied: the ID is not one of the integration's ingestion sources, the source cannot be disabled, or JupiterOne did not store the entry. UpdateFailed carries the error and is retried every 30 seconds. If the condition is missing entirely, check that the instance has been created (check the Ready condition), then check whether the field reached the resource: kubectl get integrationinstance <name> -n jupiterone -o jsonpath='{.spec.ingestionSources}'. If it is empty, either the value is not set (an empty or unset value sets no condition, so also check that your last helm upgrade did not pass other values without it), the integration chart is too old to render it (kubernetes-managed before 1.0.9; helm show values for that chart does not list ingestionSources), or the operator is older than v0.5.0 and its CRD dropped the field. Upgrade whichever is too old, run helm repo update, then run helm upgrade on the integration chart again, because a value dropped by an older CRD is not restored on its own.

Known Limitations​

  • Unable to migrate integration jobs between collectors.
  • Integration job distribution across multiple pods is still being enhanced.
  • Some integrations may not be compatible with collectors.

Contents