Getting started with Looker

Best Practices

Documentation

Community

Training

Certification

Articles in this section

See more

Auto-provisioning a new Looker instance

Avatar
Looker Support
  • Updated
Follow

Optionally, at the startup of a new Looker instance, you can automatically provision the instance with a license key, host URL, and initial user account.

Automatically provisioning a new instance with an email user

On initial startup, Looker scans for a file named provision.yml in the looker directory, where the JAR file resides. The format for this file is as follows:

license_key: "1234-5678-ABCD-EFGH-IJKL"
host_url: "https://looker.mycompany.com"
user:
  first_name: "Katie"
  last_name: "Woolsey"
  email: "kwoolsey@benaventi.com"
  password: "password123"

If the Looker instance is brand new and has not been set up yet, it will be provisioned with the given license key and a user account with the provided information.

If the Looker has already been provisioned, the license key and host URL values will override whatever license key and host URL are currently set. The user info will be ignored. This is useful for updating a staging instance of Looker with a fresh copy of a production instance’s internal database, while still maintaining a separate license key and URL for the staging server.

Automatically provisioning a new instance with an API user

At the startup of a new Looker instance, you can provision an initial API user programmatically. You can provision an API user OR an email user, but Looker does not support provisioning both an API user and an email user at the same time.

Generating API credentials

To provision an API user, generate a client ID and a client secret that Looker will read and save to the database. The requirements for these credentials are:

  • The client ID must be 20 characters in length.
  • The client secret must be 24 characters in length.
  • Both strings must be able to be included in the body of a POST request, therefore using only alphanumeric characters is recommended.

For example, Looker uses the following code to programmatically generate these credentials:

require 'securerandom' TOKEN_SYMBOLS = "bcdfghjkmnpqrstvwxyzBCDFGHJKMNPQRSTVWXYZ23456789".freeze def generate_token(size) Array.new(size).map { TOKEN_SYMBOLS[SecureRandom.random_number(TOKEN_SYMBOLS.size)] }.join end

The code above avoids ambiguous characters to make the strings less error-prone.

You can also generate suitable strings using the openssl command:

openssl rand -hex 10

The number at the end of the openssl command is the number of bytes in the string, so use 10 for the client ID and 12 for the client secret.

Provisioning the API user

To provision an API user at startup, ensure you have a provision.yml file that includes your license key and host URL in the looker directory. For example:

license_key: "1234-5678-ABCD-EFGH-IJKL"
host_url: "https://looker.mycompany.com"

Create a file called api-provision.yml with the permissions 0600 in the looker directory that includes the API user information. For example:

user:
  first_name: "Katie"
  last_name: "Woolsey"
  client_id: "M9hZb8vRh9bSZzdPxw42"
  client_secret: "NMnqBVbHqPsPzTvbZk6xZfV3"

We recommend you store these credentials in a secret manager outside of this file, as this file will be removed on startup once the Looker instance has processed and created the user in the database.

At startup, if the instance is empty and no users are present, Looker creates a Looker admin API user with these credentials and removes the api-provision.yml file from the disk.

You then have 30 minutes to use these credentials to do additional provisioning before the credentials are removed from the internal database and are no longer usable. Removing these initial credentials avoids creating a long-lived backdoor into the application and keeps the intended use case strictly to provisioning.