Install and configure Chef 360 Platform Server

This procedure installs Chef 360 Platform Server embedded in a single-node Kubernetes cluster. Chef 360 Platform operates in an underlying Kubernetes container that’s opaque to the user and extends and scales automatically in the background.

Prerequisites

• a Chef 360 Platform authorization code
• a Chef 360 Platform license
• an active internet connection

Requirements

Review the system requirements before installing Chef 360 Platform Server.

Download the installer

You can use either a web portal or curl to download Chef 360 Platform Server.

• Web portal
• curl

Install Chef 360 Platform Server

If you’ve downloaded the Chef 360 Platform installer, follow this step to install Chef 360 Platform.

• Install Chef 360 Platform by running the installer.

  For an internet-connected installation, use the following command:

  sudo ./chef-360 install --license license.yaml
  

  For an airgapped installation, use the following command:

  sudo ./chef-360 install --license license.yaml --airgap-bundle chef-360.airgap
  

  Use the --skip-host-preflights option to skip preflight checks.

  During the install process, enter your Admin Console password.

  ? Enter a new Admin Console password: ********
  ? Confirm password: ********
  Node installation finished
  Storage is ready!
  Embedded Cluster Operator is ready!
  Admin Console is ready!
  Admin Console accessible at: <LINK>
  

  The installer returns a link that you’ll use to configure Chef 360 Platform.

Configure Chef 360 Platform Server

Log into the Chef 360 Platform Admin Console using the link returned when the Chef 360 Platform Server was installed. If the Admin Console in not accessible from the IP address in the link, replace the IP address in the link provided during the install process with the public fully qualified domain name.

The installation configuration screen appears.

Configuration options

To continue with the full setup of settings and options, select Advanced Configuration, then accept the terms and conditions.

Tenant setup

This section outlines how to define your tenant setup information. You must verify your operating DNS to keep it aligned with your company’s configuration.

1. In the Tenant Name field, enter the name for your default tenant.

   Note

   Chef 360 Platform doesn’t allow underscores (_) in the tenant name.

2. In the Tenant TLD field, enter the top-level domain (TLD) name for your tenant. This is based on the DNS you have reserved for use with the Chef 360 Platform.

   For example, enter example.com.

   For a multi-level subdomain, for example sub1.sub2.example.com, enter everything after the first subdomain: sub2.example.com.

3. In the Tenant Subdomain field, enter the unique subdomain for this tenant. This is based on your DNS routing for Chef 360 Platform.

   For a single-level subdomain, for example sub1.example.com, enter the subdomain: sub1.

   For a multi-level subdomain, for example sub1.sub2.example.com, enter the first subdomain: sub1.

4. Verify the Tenant Fully Qualified Domain Name field. This is a read-only section to verify that both of the previous settings are correct based on your DNS entries.

Tenant SMTP configuration

As an add-on, Chef 360 Platform allows you to use the Mailpit mail server.

If you have chosen to use the Mailpit configuration you must update the Mailpit HTTP NodePort port setting if you decide not to use the default port.

SMTP server setup

If you use an existing SMTP server, configure these settings based on your server configuration:

1. In the SMTP Server Name field, enter the SMTP server name.

2. In the SMTP Host field, enter the SMTP host.

3. In the SMTP Port field, enter the SMTP port. The default port is 587.

4. In the SMTP Username field, enter the SMTP username.

5. In the SMTP Password field, enter the SMTP password.

6. In the SMTP Authentication Method list, select the SMTP authentication method.

7. In the Sender Email field, enter the email address your SMTP server will use as the From value when sending emails.

8. Optional: Select Enable retries to configure the number of email retries.

   In the Number of retries field, enter the number of retries. The default value is two.

9. Optional: Select Enabled TLS to enable TLS.

   This gives you two options for verifying the server’s authenticity. Do one of the following:

   • Optional: Enter a root certificate in the Root CA field.
   • Optional: Select Skip SMTP Cert Validation to skip SMTP TLS certificate verification.

Managed services

Chef 360 Platform Server uses high availability PostgreSQL to store and manage server data and uses MinIO to store Courier job data and Habitat packages hosted by an embedded deployment of Chef Habitat Builder. You can configure Chef 360 Platform to store server data using Amazon RDS for PostgreSQL and AWS S3 to store Courier job data (Habitat packages are still stored on MinIO).

PostgreSQL type

To manage server data using Amazon RDS for PostgreSQL instead of high availability PostgreSQL, follow the steps below.

Before you begin, you will need an AWS RDS user with the correct privileges. To create a user, you can use the following code example:

• This SQL command creates the replica_user user with the correct privileges to manage Chef 360 Platform job data.

  CREATE ROLE replica_user;
  GRANT rds_replication TO replica_user;
  GRANT ALL PRIVILEGES ON DATABASE postgres TO replica_user;
  ALTER USER replica_user WITH LOGIN PASSWORD '<REPLICA_PASSWORD>';
  COMMIT;
  

  Replace <REPLICA_PASSWORD> with a user password.

To configure Chef 360 Platform Server to use Amazon RDS for PostgreSQL, follow these steps:

1. Under Postgresql Type select Postgresql RDS.

   Chef 360 Platform adds the RDS Configuration section.

2. In the RDS Configuration section, enter the following details:

   • In the Writer Endpoint box, enter the RDS writer endpoint.
   • In the Writer Port box, enter the RDS writer port. The default port is 5432.
   • In the Reader Endpoint box, enter the RDS reader endpoint.
   • In the Reader Port box, enter the RDS reader port. The default port is 5432.
   • In the Master Username box, enter the RDS master username. The default username is postgres.
   • In the Master Password box, enter the RDS master password.
   • In the Replica Username box, enter the replica username for the AWS RDS instance. For example, replica_user.
   • In the Replica Password box, enter the replica user password for the of AWS RDS instance.

Storage type

To configure Chef 360 Platform Server to store Courier job data using AWS S3 instead of MinIO, follow these steps:

1. Under Storage Type select S3.

   Chef 360 Platform adds the S3 Configuration section.

2. In the S3 Configuration section, enter the following details:

   • In the Endpoint box, enter the S3 endpoint. For example, https://s3.us-west-2.amazonaws.com.
   • In the Access Key box, enter the S3 access key.
   • In the Secret Key box, enter the S3 secret key.
   • In the Region box, enter the S3 region. For example, us-west-2.

Tenant administrator

All Chef 360 Platform deployments require an admin to work with the platform. To configure the default administrator, follow these steps:

1. In the Tenant Administrator’s First Name field, enter the tenant administrator’s first name.
2. In the Tenant Administrator’s Last Name field, enter the tenant administrator’s last name.
3. In the Tenant Administrator’s Email Address field, enter the tenant administrator’s email address.

Primary tenant organization

All Chef 360 Platforms require a default organization. It’s not easy to change this after saving the configuration.

API/UI settings

1. Set the maximum body size limit in MB for the API gateway.

   The body size limit restricts the request body size for APIs. The default value is 10 MB.

2. Optional: Add an API token to manage tenant APIs.

   A token is required to create or manage tenant APIs through the internal and public gateways.

   Note

   The tenant API is experimental and subject to change.

   1. To enable the token for the public API gateway, select the Enable Install Admin Token for Public Gateway checkbox.

   2. Enter a token in the Install Admin Token field.

      Tokens have the following requirements:

      • The token must be at least 16 characters long.
      • It can include alphanumeric characters, underscores _, and hyphens -.

   For information about using the API, see the tenant API documentation.

3. Optional: Add an API token to access metrics data APIs.

   These APIs retrieve metrics data for various services and components in the Chef 360 Platform.

   Note

   The metrics APIs are experimental and subject to change.

   1. Enter a token in the Metrics API Token field.

      Tokens have the following requirements:

      • The token must be at least 16 characters long.
      • It can include alphanumeric characters, underscores _, and hyphens -.

   For information about using the APIs, see the metrics API documentation.

4. Set the reverse proxy node port.

   You can configure Chef 360 Platform to use a Chef-generated certificate or a customer-generated key. We recommend providing a secure token.

   1. Set the Gateway Nginx Reverse Proxy NodePort based on your needs. The default value is 31000.

   2. Select a Gateway Certificate Method:

      • Disabled: We don’t recommend disabling the gateway certificate.
      • System Generated: Chef 360 Platform generates a private key and certificate.
      • Custom Certificate: You upload a certificate and private key for use with the Chef 360 Platform.

      Chef 360 Platform enables TLS if you select System Generated or Custom Certificate.

   3. If you select Custom Certificate, upload a certificate chain that includes all intermediate certificates and terminates with a root CA certificate. This is required to establish a complete trust chain for secure communication. Uploading a certificate chain is mandatory for self-signed certificates or when using Windows or macOS nodes as these systems require the full chain to validate the certificate properly.

5. Optional: Set an expiration date for your public API key.

   In the Public Signature Key Expiry for API Gateway field, set an expiration date in Unix time format.

   Default value: 1924905600 (December 31, 2030).

RabbitMQ configuration

In the AMQP/AMQP-TLS NodePort field, specify the port needed to communicate with RabbitMQ. The default port is 31050.

Deploy Habitat Builder on-prem

If your deployment is airgapped or requires an on-premises Habitat Builder, select the Enable on-prem Hab Builder checkbox to deploy Habitat Builder as part of your Chef 360 Platform deployment.

Replicas count

As an advanced configuration, Chef 360 Platform allows you to configure the number of replicas for each service during deployment. The default value is one replica for each service.

Worker time to live

Workers manage and monitor jobs on Chef 360 Platform Server.

The worker time-to-live specifies the duration, in minutes, that a worker remains idle before it’s automatically terminated. This helps manage resource usage by ensuring that idle workers don’t persist indefinitely.

Enter an integer greater than or equal to 10. The default value is 10.

Save configuration

Verify that all settings are correct for the initial setup and then select Continue.

Deploy Chef 360 Platform Server

After you save your configuration, Chef 360 Platform runs preflight checks to verify your settings.

1. If there are warnings, verify that all requirements have been met. If there’s a missing setting, correct the setup and select Re-run. If you are confident that the settings are correct, select Re-run deployment and clear the indicator with Deploy anyway.

2. If all preflight checks pass, select Deploy.

   

   After deploying the Chef 360 Platform administrative console dashboard displays and the cluster status is Deploying.

   When the deployment is complete, the cluster status updates to Currently deployed version.

   

   Chef 360 Platform is now installed and you can start using it. Refer to the following sections for details on how to upgrade Chef 360 Platform.

Additional Chef 360 Platform settings

Enable automatic updates

Chef 360 Platform can automatically update itself. You can schedule how often it checks for updates and the release types it will automatically update, for example check daily and update patch releases only.

To enable automatic updates, follow these steps:

1. Log in to the Chef 360 Platform Admin Console, select the Dashboard tab and then select Configure automatic updates.

   

2. In the Configure automatic updates dialog, enter the interval to automatically check for updates. You can choose a predefined interval from the menu or create a custom interval. Then select the type of updates to automatically deploy, for example just patch releases. Then select Update.

   

   Automatic updates are enabled.

For more information, see the automatic updates and cron reference documentation.

Set an administrator password

After you install and configure Chef 360 Platform, it sends an email with a link to set an administrator password. You have five minutes to open the link in the email and set the password. If your one-time password expires, you can create a new one.

If you set up Mailpit, you can access your email in Mailpit from http://<TENANT_FQDN>:31101.

To set an administrator password:

1. Open the link in the email and create a password with at least eight characters.

2. Log into Chef 360 Platform.

3. Select your organization and role from the menu to create a user and an organization.

Generate a new one-time password

You can generate a new one-time password link if your previous one expired.

To generate a new one-time password:

1. Go to http://<TENANT_FQDN>:31000/app/login/forgot-password, enter your email address, and select Forgot Password.

   Chef 360 Platform sends an email to your email address with a link to reset your password.

2. Open the link from the email sent by Chef 360 Platform. In set your new password with at least eight characters.

   

More information

• See the Chef 360 Platform Server install documentation.

Next step

• Install the Chef 360 Platform CLIs on your computer.