Skip to main content

Chef Automate

Visualize your Chef-managed infrastructure in JupiterOne — the nodes that check in to Chef Automate, the Chef organizations, environments, and Chef Infra Servers that organize them, and each node's latest Chef Infra Client converge run with the versioned cookbooks it applied — map nodes to the Chef Infra Servers that manage them and the environments they belong to, and track failed runs, Chef Infra Client versions, and cookbook versions in use through queries and alerts.

Installation​

This integration connects to your Chef Automate instance using the Chef Automate REST API and ingests the nodes that have checked in to Automate, the Chef organizations, environments, and Chef Infra Servers they report through, and their Chef Infra Client converge runs together with the cookbooks those runs applied. It reads the infrastructure (config-mgmt) endpoints under /api/v0/cfgmgmt/ and authenticates with a Chef Automate API token. It does not use the Chef Infra Server API or its signed-request authentication, so it sees only the nodes that report to Chef Automate.

Chef Automate is usually self-hosted. If your instance is not reachable from the internet, run the integration on a JupiterOne Collector that can reach the Automate URL over HTTPS.

Configuration in Chef Automate​

Before you configure the integration in JupiterOne, prepare the following in Chef Automate:

  • The URL of your Chef Automate instance, for example https://automate.example.com. JupiterOne, or the JupiterOne Collector, must be able to reach it.

  • An API token for the integration. API tokens are the only way to authenticate against the Chef Automate API. In the Chef Automate UI, go to the Settings tab, open API Tokens, and select Create Token. Give the token a name and, optionally, assign it to a policy in the same dialog. After you create the token, open the menu at the end of its row and select Copy Token to get its value. You need the iam:tokens permission to manage tokens. Members of the admins team or the Administrator policy have it.

  • Permissions for the token. A token that isn't assigned to a policy has no permissions. The integration needs only these two read-only IAM actions:

    IAM actionNeeded for
    infra:nodes:listCredential validation (always required), and the Organizations, Chef Infra Servers, Nodes, and Environments data sources. It's also used to list run history for Node Runs
    infra:nodes:getNode Runs: reading each converge run report

    Do one of the following:

    • Add the token to the Chef-managed Viewers policy. This policy grants read-only access to everything in Chef Automate except IAM, including both actions above.
    • Create a custom policy that grants only infra:nodes:list and infra:nodes:get, and add the token to it. You can only create custom policies with the Chef Automate Policies API (POST /apis/iam/v2/policies).

    To add the token to an existing policy, go to Settings, open Policies, open the policy, select Add Members, then Add Member Expression, and enter token:<token-id>. The token ID is shown on the API Tokens page.

    If the policy only covers some Chef Automate projects, the token only sees the nodes assigned to those projects. Scope the policy to every project ("projects": ["*"]) to ingest your whole estate.

  • If Chef Automate presents a self-signed or internal-CA TLS certificate, get the CA certificate in PEM format so the integration can verify the connection.

Once you have obtained the information above, proceed to JupiterOne to finalize the integration.

Configuration in JupiterOne​

To install the Chef Automate integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Chef Automate. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Chef Automate 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.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • The Authentication and Options fields below.

Authentication fields​

FieldRequiredDescription
Chef Automate URLYesBase URL of your Chef Automate instance, for example https://automate.example.com. Any trailing slash is removed.
API TokenYesThe Chef Automate API token created above. It's sent in the api-token request header. The token must belong to a policy that grants the infra:nodes:list and infra:nodes:get actions.

When you save the instance, the integration checks the credentials by calling GET /api/v0/cfgmgmt/organizations.

Options fields​

FieldRequiredDefaultDescription
Disable TLS VerificationNoOffSkips TLS certificate verification. Not recommended. Use it only for a self-signed, on-premises Chef Automate instance, and use CA Certificate instead where you can.
CA CertificateNoEmptyCA certificate (PEM) used to verify a Chef Automate instance that presents a self-signed or internal-CA-signed TLS certificate.
Include Run HistoryNoOffWhen off, only the latest converge run of each node is ingested. When on, every run Chef Automate still holds for each node is ingested. Only applies when the Node Runs data source is enabled.
OrganizationsNoEmpty (all)Ingest only nodes in these Chef organizations. Leave empty to ingest all.
EnvironmentsNoEmpty (all)Ingest only nodes in these Chef environments. Leave empty to ingest all.

Organizations and Environments are sent to Chef Automate as node filters. Values in the same list are combined with OR, and the two lists are combined with AND. They restrict the nodes, and so also the environments, runs, and cookbooks derived from those nodes. They don't restrict the Organizations and Chef Infra Servers data sources, which always list every organization and Chef Infra Server known to Chef Automate.

Click Create once all values are provided to finalize the integration.

Data Sources​

Each data source can be enabled or disabled on its own. All data sources are disabled by default, so enable the ones you want to ingest. The chef_account entity (the Chef Automate instance) and the chef_service entity are always created.

Data SourceDescriptionEntities Created
OrganizationsChef organizations associated with checked-in nodeschef_organization
Chef Infra ServersChef Infra Servers that managed nodes report through, identified by FQDNchef_infra_server
EnvironmentsChef environments of the ingested nodes. Requires Nodeschef_environment
NodesChef-managed infrastructure nodes checked in to Chef Automate, with hostname, FQDN, IP and MAC addresses, platform, Chef Infra Client version, policy, and check-in statuschef_node
Node RunsChef Infra Client converge runs and the versioned cookbooks they applied. Requires Nodeschef_run, chef_cookbook

Some relationships, and two data sources, need more than one data source to be enabled:

  • Organization to node (HAS) requires Organizations and Nodes.
  • Chef Infra Server to node (MANAGES) requires Chef Infra Servers and Nodes.
  • Environments requires Nodes. Chef Automate has no complete environment list, so environments are built from the nodes that were ingested. It also creates the environment to node (HAS) relationship.
  • Node Runs requires Nodes. It creates the node to run (HAS) and run to cookbook (USES) relationships.

The integration doesn't create mapped relationships to entities from other integrations.

Limits and behavior​

  • 10,000-result limit. Chef Automate serves the node list and each node's run history from its search backend (Elasticsearch or OpenSearch). That backend returns at most 10,000 results for a single query by default (index.max_result_window). If more than 10,000 nodes match your filters, Chef Automate returns an error for the pages past that point and the Nodes step fails. If you have more than 10,000 nodes, split them across several integration instances with the Organizations or Environments filters, or ask your Chef Automate administrator to raise index.max_result_window. The same limit applies to each node's run history when Include Run History is enabled.
  • Run volume. By default, one run (the latest) is ingested per node. With Include Run History enabled, the integration makes one extra API request for every run. Run data is kept in Chef Automate only as long as its data lifecycle settings allow (30 days by default).
  • Nodes without runs. A node appears in Chef Automate after a Chef Infra Client run completes, but a node can be listed with no run history. Such nodes are ingested as chef_node entities and skipped by Node Runs.
  • Missing nodes. Chef Automate labels nodes that stop checking in as missing, and later deletes them, based on its data lifecycle settings. A deleted node disappears from JupiterOne on the next run.
  • Environment identity. Environments are scoped to a Chef Infra Server and an organization, so environments with the same name (for example production) in different organizations or servers become separate chef_environment entities.
  • Chef Infra Servers. Chef Automate only exposes each server's FQDN, so chef_infra_server entities carry the FQDN and no other host details.
  • Not collected. Node attributes, per-resource run details (including resource diffs), compliance reports, and the event feed aren't collected.

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.

Additional resources​