Skip to main content

Kubernetes Managed

Visualize Kubernetes resources and monitor changes through queries and alerts.

Installation​

Prerequisites​

Moving from Kubernetes Native?

See the Migration tab for the full cutover sequence, data model differences, and answers to common migration questions.

Before installing the Kubernetes Managed integration, you must have a Kubernetes collector running. For instructions on setting up the Kubernetes collector, see the Kubernetes collector documentation.

Configuration in JupiterOne​

  1. Navigate to the Integrations tab in JupiterOne and select Kubernetes Managed.

  2. Click New Instance to begin configuring your integration and provide the following:

    • The Account Name used to identify the Kubernetes account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

    • Description to assist in identifying the integration instance, if desired.

    • When prompted about where should this run, select the Kubernetes collector you created in the prerequisites.

    • Use Default Kubernetes Configuration (optional): Enable when running the integration outside of a Kubernetes cluster, such as on a local machine. When disabled, the integration uses the cluster's built-in in-cluster authentication. Disabled by default.

    • Ingest All Node Images (optional): Enable to ingest every image cached on each node, instead of only the images in use by a running container. Required to ingest images at all if you are not ingesting pods. Disabled by default. See Image ingestion.

  3. Click Create after all values are provided and your instance appears in the list of all your Kubernetes Managed instances.

Data Volume Configuration​

By default, the integration ingests all namespaces in your cluster. Use the options below to limit which namespaces are included.

Data Filtering Options​

FieldDescriptionDefault
Include Specific NamespacesRestrict ingestion to the listed namespaces only. Separate names with commas. If left empty, all namespaces are ingested (unless exclusions are specified).All namespaces
Exclude Specific NamespacesSkip the listed namespaces during ingestion. Useful for omitting system namespaces such as kube-system. Separate names with commas.None

Image ingestion​

By default, kube_image entities are created only for images in use by a running container, and each container is linked to its image with a kube_container USES kube_image relationship. Images are derived from pods, so a cluster that does not ingest pods produces no images.

Enable Ingest All Node Images (ingestAllNodeImages) to also ingest the images cached on each node, whether or not a container is running them, and to relate each node to the images it holds with kube_node HAS kube_image. This is the option to use if you are not ingesting pods and still want image inventory.

FieldDescriptionDefault
Ingest All Node ImagesIngest every image in each node's local image cache in addition to the images in use by a running container.Disabled
kubelet limits how many images a node reports

A node reports its cached images through Node.status.images, which kubelet truncates at --node-status-max-images (default 50, -1 disables the limit) and which only covers images present in that node's local cache. Enabling this option therefore gives a best-effort inventory per node rather than a guaranteed complete one. Set --node-status-max-images=-1 on your kubelets if you need the full list.

RBAC​

The Kubernetes collector installs with a ClusterRole that provides read-only access to Kubernetes resources. The collector has permissions to get, list, and watch the following:

Core Resources:

  • Pods, namespaces, service accounts, config maps, nodes, services, secrets, and events

Application Workloads:

  • Deployments, replica sets, stateful sets, daemon sets, jobs, and cron jobs

Networking:

  • Ingresses and network policies

RBAC and Security:

  • Cluster roles, cluster role bindings, roles, and role bindings
  • Self-subject access reviews and subject access reviews
  • Token reviews

Extensions:

  • All resources in the extensions API group

Integration Management:

  • Integration instance jobs, integration runners, and their status and finalizers (for managing integration workloads)

All permissions are read-only (get, list, watch) and do not allow modification of any cluster resources.

Advanced: Configuring Custom Resource Definitions (CRDs)​

By default, the Kubernetes Managed integration ingests standard Kubernetes resources. However, you can extend the integration to also collect and map Custom Resource Definitions (CRDs) that exist in your cluster. This is particularly useful for capturing custom resources created by operators, such as IntegrationRunners and IntegrationInstanceJobs from the JupiterOne Kubernetes Operator.

Overview​

The CRD configuration allows you to:

  • Define which custom resources to ingest: Specify the CRD resources you want to collect from your cluster
  • Map resource properties: Transform CRD fields into JupiterOne entity properties
  • Create relationships: Define how custom resources relate to other entities in your JupiterOne graph

Configuration File Structure​

The CRD configuration is defined in a YAML file with two main sections: resources and relationships. This configuration file can be provided when setting up your integration instance.

Resources Section​

The resources section defines which custom resources to ingest and how to map their properties to JupiterOne entities.

Each resource entry contains:

  • name (required): The fully qualified name of the CRD resource type, following the format <plural>.<group>. For example, integrationrunners.integrations.jupiterone.io refers to the IntegrationRunner CRD in the integrations.jupiterone.io API group.

  • version (optional): The API version of the resource. For example, v1 indicates the resource uses version 1 of the API. If not provided, all versions will be ingested.

  • _type (required): The entity type that will be assigned to ingested resources in JupiterOne. This is a custom identifier that you'll use to query and reference these entities. It should follow the pattern kube_cr_<resource_name> (e.g., kube_cr_integration_runner).

  • _class (required): The entity class that categorizes the resource in JupiterOne's data model. All supported entity classes can be found in the JupiterOne Data Model documentation.

  • propertyToFieldMap (required): A mapping that defines how fields from the Kubernetes resource are transformed into JupiterOne entity properties. This is where you specify which Kubernetes resource fields map to which JupiterOne properties.

    • _key (required): Maps to the unique identifier for the entity in JupiterOne. It's recommended to use metadata.uid to ensure uniqueness.
    • Standard properties: Common mappings include:
      • name: Usually maps to metadata.name
      • namespace: Usually maps to metadata.namespace
      • createdOn: Usually maps to metadata.creationTimestamp
    • Custom properties: You can map any field from the resource's spec or status sections to custom properties. For example, accountId: spec.accountId maps the accountId field from the resource's spec to a property called accountId on the JupiterOne entity.

Relationships Section​

The relationships section defines how custom resources relate to other entities in your JupiterOne graph. This allows you to create meaningful connections between resources, such as showing which secrets an IntegrationRunner uses or which runner an IntegrationInstanceJob runs on.

Each relationship entry contains:

  • _class (required): The type of relationship. All supported relationship classes can be found in the JupiterOne Data Model documentation.

  • sourceType (required): The entity type of the source entity in the relationship. This should match the _type you defined in the resources section (e.g., kube_cr_integration_runner).

  • targetType (required): The entity type of the target entity in the relationship. This can be:

    • Another custom resource type you've defined (e.g., kube_cr_integration_instance_job)
    • A standard Kubernetes resource type (e.g., kube_secret, kube_pod, kube_namespace)

  • matchBy (required): Defines how to match the source and target entities to create the relationship. This is a key-value mapping where:

    • The key is a property name on the source entity (e.g., secretName)
    • The value is a property name on the target entity (e.g., name)

    The relationship is created when the source entity's property value matches the target entity's property value. You can specify multiple match conditions, and all must be satisfied (AND logic). For example:

    matchBy:
      secretName: name
      namespace: namespace

    This creates a relationship when both the secretName on the source matches the name on the target, AND the namespace on the source matches the namespace on the target.

    note

    If a property is not defined for either the source or the target, the relationship won't be created. Undefined doesn't match with undefined.

Example Configuration​

Here's a complete example configuration that ingests IntegrationRunners and IntegrationInstanceJobs and creates relationships between them and their associated secrets:

resources:
  - name: integrationrunners.integrations.jupiterone.io
    version: v1
    _type: kube_cr_integration_runner
    _class: Process
    propertyToFieldMap:
      _key: metadata.uid
      name: metadata.name
      namespace: metadata.namespace
      createdOn: metadata.creationTimestamp
      accountId: spec.accountId
      collectorId: spec.collectorId
      collectorPoolId: spec.collectorPoolId
      jupiterOneEnvironment: spec.jupiterOneEnvironment
      secretAPITokenName: spec.secretAPITokenName
      secretName: spec.secretName
      syncIntervalSeconds: spec.syncIntervalSeconds

  - name: integrationinstancejobs.integrations.jupiterone.io
    _type: kube_cr_integration_instance_job
    _class: Task
    propertyToFieldMap:
      _key: metadata.uid
      name: metadata.name
      namespace: metadata.namespace
      createdOn: metadata.creationTimestamp
      accountId: spec.accountId
      certificateIdentity: spec.certificateIdentity
      image: spec.image
      integrationDefinitionName: spec.integrationDefinitionName
      integrationInstanceId: spec.integrationInstanceId
      integrationInstanceJobId: spec.integrationInstanceJobId
      integrationRunnerName: spec.integrationRunnerName
      secretName: spec.secretName

relationships:
  - _class: HAS
    sourceType: kube_cr_integration_runner
    targetType: kube_secret
    matchBy:
      secretName: name
      namespace: namespace

  - _class: HAS
    sourceType: kube_cr_integration_instance_job
    targetType: kube_secret
    matchBy:
      secretName: name
      namespace: namespace

  - _class: HAS
    sourceType: kube_cr_integration_instance_job
    targetType: kube_cr_integration_runner
    matchBy:
      integrationRunnerName: name
      namespace: namespace

Understanding the Example​

Resources Explained:

  1. IntegrationRunner Resource:

    • Ingested as kube_cr_integration_runner entities with class Process
    • Maps standard Kubernetes metadata (uid, name, namespace, creationTimestamp)
    • Maps custom spec fields like accountId, collectorId, and syncIntervalSeconds to entity properties
    • The secretName property is used later to create relationships with secrets

  2. IntegrationInstanceJob Resource:

    • Ingested as kube_cr_integration_instance_job entities with class Task
    • Similar metadata mapping
    • Maps job-specific fields like integrationInstanceId, image, and integrationRunnerName
    • The integrationRunnerName property links jobs to their runners

Relationships Explained:

  1. IntegrationRunner → Secret:

    • Creates a HAS relationship from each IntegrationRunner to the secret it uses
    • Matches when the runner's secretName equals the secret's name AND they're in the same namespace

  2. IntegrationInstanceJob → Secret:

    • Creates a HAS relationship from each IntegrationInstanceJob to its associated secret
    • Uses the same matching logic as above

  3. IntegrationInstanceJob → IntegrationRunner:

    • Creates a HAS relationship showing which runner executes each job
    • Matches when the job's integrationRunnerName equals the runner's name AND they're in the same namespace

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.