Integration

Integrations that Anchore Supports

• Container Registries via the API
• Container Registries via the GUI
• CI/CD
• Kubernetes
• ECS
• Git
• ServiceNow

Integration handling in Enterprise

With v5.11.0 release, Anchore Enterprise introduces an API so that the software entities (agents, plugins, etc.) that integrate external systems with Enterprise can be tracked and monitored.

As of v5.11.0, only the Kubernetes Inventory agent uses this API. Existing versions of agents and plugins will continue to work as before but will not be possible to track and monitor with the new functionality.

This new feature and its API has broadly two parts: integration registration and integration health reporting. These will be discussed further below.

Terminology

Integration instance: A software entity, like an agent or plugin, that integrates and external system with Anchore Enterprise. A deployed Kubernetes Inventory agent, Kubernetes Admission Controller, and ECS Inventory agent are all examples of integration instances.

Integration status: The (life-cycle) status of the integration instance as perceived by Enterprise. After registration is completed, this status is determined based on if health reports are received or not.

Reported status: The status of the integration instance as perceived by the integration instance itself. This is determined from the contents of the health reports, if they contain any errors or not.

Integration registration

When an integration instance that supports integration registration and health reporting is started it will perform registration with Anchore Enterprise. This is a kind of handshake where the integration instance introduces itself, declaring which type it is and presenting various other information about itself. In response, Anchore Enterprise provides the integration instance with the uuid that identifies the integration instance from that point onwards.

The registration request includes two identifiers: registration_id and registration_instance_id. Anchore Enterprise maintains a record of the association between integration uuid and <registration_id, registration_instance_id>.

If an integration instance is restarted, it will perform registration again. Assuming the <registration_id, registration_instance_id> pair in that re-registration remains the same as in the original registration, Enterprise will consider the integration instance to be the same (and thus provide the integration instance with the same uuid). Should the <registration_id, registration_instance_id> pair be different, then Enterprise will consider the integration instance to be different and assign it a new uuid.

Integrations deployed as multiple replicas

An integration can be deployed as multiple replicas. An example is the Kubernetes Inventory agent, which helm chart deploys it as a K8s Deployment. That deployment can be specified to have replicas > 1 (although it is not advisable as the agent is strictly speaking not implemented to be executed as multiple replicas, it will work but only add unnecessary load).

In such a case, each replica will have identical configuration. They will register as integration instances and be given their own uuid. By inspecting the registration_id and registration_instance_id it is often possible to determine if they instances are part of the same replica set. They will then have registered with identical registration_id but different registration_instance_id. The exception is if each integration instance self-generated a unique registration_id that they used during registration. In that case they cannot be identified to belong to the same replica set this way.

Integration health reporting

Once registered, an integration instance can send periodic health reports to Anchore Enterprise. The interval between two health reports can be configured to be 30 to 600 seconds. A default values will typically be 60 seconds.

Each health report includes a uuid that identifies it and timestamp when it was sent. These can be used when searching the integration instance’s log file during troubleshooting. The health report also includes the uptime of the integration instance as well as an ’errors’ property that contains errors that the integration wants to make Anchore Enterprise aware of. In addition to the above, health reports can also include data specific to the type of integration.

Reported status derived from health reports

When Anchore Enterprise receives a health report that contains errors from an integration instance, it will set that instance’s reportedStatus.state to unhealthy and the reportedStatus.healthReportUuid is set to the uuid of the health report. If subsequent health reports do no contain errors, the instance’s reportedStatus.state is set to healthy and the reportedStatus.healthReportUuid is unset.

This is an example of what the reported status can look like from an integration instance that sends health reports indicating errors:

{
    "reportedStatus": {
      "details": {
        "errors": [
          "unable to report Inventory to Anchore account account0: failed to report data to Anchore: \u0026{Status:4",
          "user account not found (account1) | ",
          "unable to report Inventory to Anchore account account2: failed to report data to Anchore: \u0026{Status:4",
          "user account not found (account3) | "
        ],
        "healthReportUuid": "d676f221-0cc7-485e-b909-a5a1dd8d244e"
      },
      "reason": "Health report included errors",
      "state": "unhealthy"
    }
}

The details.errors list indicates that there is some issues related to ‘account0’, ‘account1’, ‘account2’ and ‘account3’. To fully triage and troubleshoot these issues one will typically have to search the log file for the integration instance.

This is an example of reported status for case without errors:

{
    "reportedStatus": {
      "state": "healthy"
    }
}

The below figure illustrates how the reportedStatus.state property will transition between its states.

Integration status derived from health reports

When an integration instance registers with Anchore Enterprise, it will declare at what interval it will send health reports. A typical value will be 60 seconds.

As long as health reports are received from an integration instance, Enterprise will consider it to be active. This is reflected in the integration instance’s integrationStatus.state which is set to active.

If three (3) consecutive health reports fail to be received by Anchore Enterprise, it will set the integration instance’s integrationStatus.state to inactive.

This is an example of what the integration status can look like when health reports have not been received from an integration instance:

{
  "integrationStatus": {
    "reason": "Integration last_seen timestamp is older than 2024-10-21 15:33:07.534974",
    "state": "inactive",
    "updatedAt": "2024-10-21T15:46:07Z"
    }
}

A next step to triage this could be to check if the integration instance is actually running or if there is some network connectivity issue preventing health reports from being received.

This is an example of integration status when health reports are received as expected:

{
  "integrationStatus": {
    "state": "active",
    "updatedAt": "2024-10-21T08:21:01Z"
  }
}

The below figure illustrates how the integrationStatus.state will transition between its (lifecycle) states.

Integration instance properties

An integration instance has the below properties. Some properties may not have a value.

• accountName: The account that integration instance used during registration (and thus belongs to).
• accounts: List of account names that the integration instance handles. The list is updated from information contained in health reports from the integration instance. For the Kubernetes Inventory agent, this list holds all accounts that the agent has recently attempted to send inventory reports for (regardless if the attempt succeeded or not).
• clusterName: The cluster where the integration instance executes. This will typically be a Kubernetes cluster.
• description: Short arbitrary text description of the integration instance.
• explicitlyAccountBound: List of account names that the integration instance is explicitly configured to handle. This does not include account names that an integration instance could learn dynamically. For instance, the Kubernetes Inventory agent can learn about account names to handle via a special label set on the namespaces. Such account names are not included in this property.
• healthReportInterval: Interval in seconds between health reports from the integration instance.
• integrationStatus: The (life cycle) status of the integration instance.
• lastSeen: Timestamp when the last health report was received from the integration instance.
• name: Name of the integration instance.
• namespace: The namespace where the integration executes. This will typically be a Kubernetes namespace.
• namespaces: List of namespaces that the integration is explicitly configured to handle.
• registrationId: Registration id that the integration instance used during registration.
• registrationInstanceId: Registration instance id that the integration instance used during registration.
• "reportedStatus: The health status of the integration instance derived from information reported in the last health report.
• startedAt: Timestamp when the integration instance was started.
• type: The type of the integration instance. In Enterprise v5.11.0, k8s_inventory_agent is the only value.
• uptime: Uptime (in seconds) of the integration instance.
• username: Username that the integration instance registered using.
• uuid: The UUID of the integration instance. Used in REST API to specify instance.
• version: Software version that the integration instance runs.