Optionally, at the startup of a new Looker customer-hosted 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: "Ariel"
last_name: "Q"
email: "arielq@altostrat.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: "Ariel"
last_name: "Q"
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.