Skip to main content

Kubernetes Managed

Visualize Kubernetes resources and monitor changes through queries and alerts.

Installation​

Prerequisites​

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.

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

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 repository.

  • 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.