Azure VPC Setup Guide¶
This topic describes how to set up Puddle on Azure Cloud. This topic is divided into multiple sections:
- Puddle for Azure Architecture
- Setting up Azure Resources like a resource group, vnet, etc.
- Setting up Runtime Dependencies like PostgreSQL database and Redis
- Setting up the Puddle Application
Puddle for Azure Architecture¶
The image below describes the components that work together to build and run Puddle for Azure.
Set up Azure Resources¶
The first step is to set up Azure resources. All of these operations require a user login in at portal.azure.com.
Create a Resource Group¶
- After you are logged in to Azure, go to the Resource groups blade.
- Click Add.
- Fill in the form.
- Remember the name. We will need the name in later steps.
- Remember the location. We will need the location in later steps.
- Click Create.
Create a Network Security Group¶
- Search for Network security groups. Note: Do not use the option with (classic) suffix.
- Click Add.
- Fill in the form.
- Place the Network security group into the Resource group created in first step.
- Set the location of the Network security group to the same value that you specifed when creating the Resource group.
- Remember the name of the Network security group. We will need the name in later steps.
- Click Create.
- Select the newly created Network security group.
- Select Inbound security rules.
- Click Add.
- Set
22, 8888, 12345, 54321
as the Destination port ranges.22
is SSH. We need to open this port to be able to SSH into Virtual machines launched by Puddle.8888
is Jupyter. We need to open this port to be able to access Jupyter.12345
is the Driverless AI UI. We need to open this port to be able to access Driverless AI.54321
is H2O-3. We need to open this port to be able to access H2O-3 and H2O Flow.
Create Virtual Network and Subnet¶
- Go to the Virtual networks blade.
- Click Add.
- Fill in the form.
- Place the Virtual network into the Resource group created in the first step.
- Set the location of the Virtual network to the same value that you specifed when creating the Resource group.
- Remember the name of the Virtual network. We will need the name in later steps.
- Remember the name of the Subnet. We will need the name in later steps.
Create a Virtual Machine¶
Go to the Virtual Machines blade.
Click Add.
Fill in the form.
- Place the Virtual machine into the Resource group created in the first step.
- Set the location of the Virtual machine to the same location you created in the first step.
- Use Ubuntu Server 18.04 LTS as Image.
- Select Standard B2s as Size.
- Select the Authentication type that best suites your needs. Note that the SSH public key is strongly recommended.
Click Next: Disks.
Under OS disk type, select Standard SSD.
Click Next: Networking.
Under Virtual network, specify the Virtual network created in the previous step.
Under Subnet, specify the Subnet created in the previous step.
Set NIC network security group to Advanced.
Click Review + create.
Click Create.
Wait for provisioning to complete.
Go to the Virtual machines blade.
Select the newly created Virtual machine.
Click on Configure next to DNS name.
Set Static under Assignment.
Pick a DNS name. We will need this DNS name later.
Click Save.
Go back to the newly created Virtual machine.
Select Networking.
There should be two security groups available. Make sure the one not explicitly created has rules that allow inbound from ports 22, 80 and 433.
If you do not want to allow HTTP connections, then port 80 should not be allowed.
If you need to add a rule, then click on Add inbound port rule and fill in the form.
- set
22
,443
and possibly80
under the destination port ranges.
- set
Click Add.
Create App Registration and Enterprise Application¶
- Go to Azure Active Directory blade.
- Select App Registrations.
- Click New registration.
- Fill in the form.
- In Supported account types, select Accounts in this organizational directory only (msmarketplaceh2o (Default Directory)).
- Remember the name of the app registration. We will need the name in later steps.
- This will create the Enterprise application as well.
- Click Register.
- Select Manifest.
- Set the “appRoles” key to the following value:
json "appRoles": [ { "allowedMemberTypes": [ "User" ], "description": "Users have basic set of permissions in Puddle.", "displayName": "User", "id": "77e5fac4-3f2a-497d-a70f-1c3e9ac72c83", "isEnabled": true, "lang": null, "origin": "Application", "value": "User" }, { "allowedMemberTypes": [ "User" ], "description": "Administrators have extended permissions in Puddle.", "displayName": "Administrator", "id": "d1c2ade8-98f8-45fd-aa4a-6d06b947c66f", "isEnabled": true, "lang": null, "origin": "Application", "value": "Administrator" } ]Each role definition in this manifest must have a different valid GUID for the
id
key. We will need theid
of theAdministrator
role in later steps.
- Click Save.
- Select Authentication.
- Add Redirect URI with a value of
https://<Puddle Server DNS>/login-azure-callback
. - Enable both Access tokens and ID Tokens.
- Click Save.
- Go to the Azure Active Directory blade.
- Select Enterprise applications.
- Select the newly created application.
- Select the Properties blade.
- Set Yes for the Enabled for users to sign-in? option.
- If you want only selected users to be able to log in, then set User assignment required? to Yes.
- Set Visible to users? to Yes.
- Click Save.
Create First Administrator¶
- Go to the Azure Active Directory blade.
- Select Enterprise applications.
- Select Users and groups.
- Click Add user.
- Select the desired user.
- Click Select.
- Assign the Administrator role.
- Click Select.
- Click Assign.
These steps can be used to add as many Administrators as required. The User role is used to revoke the Administrator access for the user.
Add Roles to Service Principal¶
- Go to the Resource groups blade.
- Select the newly created Resource group.
- Select Access control (IAM).
- Select Role assignments.
- Click Add.
- Set Owner as Role.
- Fill in the App name to Select.
- Click Save.
- Click Add.
- Set User Access Administrator as Role.
- Fill in the App name to Select.
- Click Save.
Runtime Dependencies¶
After the basic setup of Azure resources is completed, the next step is to set up runtime dependencies for Puddle.
PostgreSQL Database¶
Run the following steps to provision the PostgreSQL database.
- Search for Azure Database for PostgreSQL servers.
- Click Add.
- Fill in the form.
Place the PostgreSQL database into the Resource group created in the first step.
Set the location of the PostgreSQL database to the location that you specified in the first step.
Remember the Server admin login name and Password. We will need them in later steps.
Set the version to 9.6.
Click on Pricing tier.
- Select Basic.
- Set vCore to 2 vCores.
- Set storage to 50GB.
- Click Create to begin provisioning.
Provisioning of the PostgreSQL database will take a few minutes, but we can continue with other steps.
Redis¶
Run the following steps to provision Redis.
- Search for Azure Cache for Redis.
- Click Add.
- Fill in the form.
- Place the Redis into the Resource group created in first step.
- Set the location of the Redis to the same location that you specified in the first step.
- Set Pricing tier to Standard C1.
- Click Create
Provisioning of the Redis will take a few minutes, but we can continue with other steps.
Puddle Application¶
For this part, we will need to create a Virtual machine where the Puddle application will run. Then we will configure nginx and create a configuration file for Puddle. After those are complete, we can start Puddle.
Additional PostgreSQL Configuration¶
- Search for Azure Database for PostgreSQL servers.
- Select the newly created database.
- Select Connection security.
- Click Add client IP.
- Use the Public IP of the Virtual machine as the Start IP and End IP.
- Click Save.
Review the Resource Group¶
The newly created Resource group should now contain these items (some of them are created implicitly):
- Azure Database for PostgreSQL server
- Azure Cache for Redis
- Virtual machine
- Disk
- Network interface
- Public IP address
- Network security group
- Storage account
- Network security group
Create the License File¶
- ssh into the Virtual Machine.
- Create a file
/opt/h2oai/puddle/license.sig
containing the license. Different path might be used, but this is the default.
Configuring Puddle¶
Now we will need to fill in the config.yaml file, which is located at /etc/puddle/config.yaml
. The config.yaml should contain the following:
redis:
connection:
protocol: tcp
address:
password:
tls: true
db:
connection:
drivername: postgres
host:
port: 5432
user:
dbname: puddle
sslmode: require
password:
tls:
certFile:
keyFile:
license:
file: /opt/h2oai/puddle/license.sig
ssh:
publicKey: /opt/h2oai/puddle/ssh/id_rsa.pub
privateKey: /opt/h2oai/puddle/ssh/id_rsa
auth:
token:
secret:
activeDirectory:
enabled: false
server:
port: 389
baseDN:
security: tls
objectGUIDAttr: objectGUID
displayNameAttr: displayName
administratorsGroup: Puddle-Administrators
usersGroup: Puddle-Users
implicitGrant: false
azureAD:
enabled: false
useAADLoginExtension: true
awsCognito:
enabled: false
userPoolId:
userPoolWebClientId:
domain:
redirectSignIn:
redirectSignOut:
adminsGroup: Puddle-Administrators
usersGroup: Puddle-Users
implicitGrant: false
ldap:
enabled: false
host:
port: 389
baseDN:
baseDNGroup:
bindDN:
bindPassword:
implicitGrant: false
adminsGroup: Puddle-Administrators
usersGroup: Puddle-Users
packer:
path: /opt/h2oai/puddle/deps/packer
usePublicIP: true
terraform:
path: /opt/h2oai/puddle/deps/terraform
usePublicIP: true
backend:
baseUrl:
connections:
usePublicIP: true
webclient:
usePublicIP: true
providers:
azure:
enabled: false
authority:
location:
rg:
vnetrg:
vnet:
sg:
subnet:
enterpriseApplicationObjectId:
adminRoleId:
publicIpEnabled: true
packerInstanceType:
aws:
enabled: false
owner:
vpcId:
sgId:
subnetId:
publicIpEnabled: true
packerInstanceType:
products:
dai:
configTomlTemplatePath:
license:
logs:
dir: /opt/h2oai/puddle/logs
maxSize: 1000
maxBackups: 15
maxAge: 60
compress: true
mailing:
enabled: true
server:
username:
password:
fromAddress: puddle@h2o.ai
fromName: Puddle
recipients:
offsetHours: 24
- ssh into the Virtual machine.
- Fill in the fields in the config.yaml.
- Values for
redis.connection.*
can be found in following way:
- Microsoft Azure:
- Search for Azure Cache for Redis.
- Select newly created Redis instance.
- Select Access keys.
- Amazon AWS:
- Go to ElastiCache Dashboard.
- Select Redis.
- Select cluster used by Puddle.
- Select Description tab.
- Values for
db.connection.*
can be found in following way:
- Microsoft Azure:
- Search for Azure Database for PostgreSQL servers.
- Select the newly created PostgreSQL instance.
- Select Connection strings.
- Use the password that was provided when creating the PostgreSQL database.
- Amazon AWS:
- Go to Amazon RDS.
- Select Databases.
- Select database used by Puddle.
tls.certFile
should point to the PEM encoded certificate file if you want to use HTTPS. If you don’t want to use HTTPS, leave this property empty. If you set this property, thentls.keyFile
must be set as well.tls.keyFile
should point to the PEM encoded private key file if you want to use HTTPS. The private key must be not encrypted by password. If you don’t want to use HTTPS, leave this property empty. If you set this property, thentls.certFile
must be set as well.license.file
should be a path to the file containing the license (created in previous step).ssh.publicKey
should be the path to ssh public key (for example /opt/h2oai/puddle/ssh/id_rsa.pub), which will be used by Puddle to talk to the Systems. If this ssh key is changed, Puddle won’t be able to talk to the Systems created with old key, and these will have to be destroyed.ssh.privateKey
should be the path to ssh private key (for example /opt/h2oai/puddle/ssh/id_rsa), which will be used by Puddle to talk to the Systems. If this ssh key is changed, Puddle won’t be able to talk to the Systems created with old key, and these will have to be destroyed.auth.token.secret
should be a random string. It is used to encrypt the tokens between the backend and frontend.
for example the following could be used to generate the secret:
tr -cd '[:alnum:]' < /dev/urandom | fold -w32 | head -n1
auth.activeDirectory.enabled
should be true/false and is false by default. If true then authentication using ActiveDirectory is enabled.auth.activeDirectory.server
should be the hostname of the ActiveDirectory server, for example puddle-ad.h2o.ai.auth.activeDirectory.port
should be the port where ActiveDirectory is accessible, defaults to 389.auth.activeDirectory.baseDN
should be the BaseDN used for search.auth.activeDirectory.security
should be the security level used in communication with AD server. Could be none, start_tls, tls, defaults to tls.auth.activeDirectory.objectGUIDAttr
should be the name of the attribute used as ID of the user, defaults to objectGUID.auth.activeDirectory.displayNameAttr
should be the name of the attribute used to determine groups where user is member, defaults to memberOf.auth.activeDirectory.administratorsGroup
should be the name of the Administrators group. Users in this group are assigned Administrator role in Puddle, users in Administrators group and Users group are considered Administrators.auth.activeDirectory.usersGroup
should be the name of the Users group. Users in this group are assigned User role in Puddle, users in Administrators group and Users group are considered Administrators.auth.activeDirectory.implicitGrant
should be true/false and is false by default. If true, then users are allowed access to Puddle (using user role) even if they are not members of Administrators nor Users group. If false, then users must be members of at least one group to be allowed access to Puddle.auth.azureAD.enabled
should be true/false and is false by default. If true, then authentication using Azure Active Directory is enabled.auth.azureAD.useAADLoginExtension
should be true/false and is false by default. If true, then ssh access to provisioned Virtual machines will use the Azure AD for authentication. Check https://docs.microsoft.com/en-us/azure/virtual-machines/linux/login-using-aad for more information. Cannot be enabled, if using proxy for egress.auth.awsCognito.enabled
should be true/false and is false by default. If true, then authentication using AWS Cognito is enabled.auth.awsCognito.userPoolId
should be the Pool Id, for example us-east-1_SlxxxxML1.auth.awsCognito.userPoolWebClientId
should be the App client id.
- The App client id can be found in following way:
- Go to the AWS Cognito User Pool used by Puddle.
- Select the App client settings.
- Use the value under ID.
auth.awsCognito.domain
should be the domain of the AWS Cognito User Pool, for example https://puddle.auth.<REGION>.amazoncognito.com.
- The domain can be found in following way:
- Go to the AWS Cognito User Pool used by Puddle.
- Select the Domain name.
auth.awsCognito.redirectSignIn
should be https://<SERVER_ADDRESS>/aws-cognito-callback, please replace <SERVER_ADDRESS> with hostname where Puddle is running.auth.awsCognito.redirectSignOut
should be https://<SERVER_ADDRESS>/logout, please replace <SERVER_ADDRESS> with hostname where Puddle is running.auth.awsCognito.adminsGroup
should be the name of a group in AWS Cognito User Pool. If users are members of this group, they are assigned Administrator role in Puddle.auth.awsCognito.usersGroup
should be the name of a group in AWS Cognito User Pool. If users are members of this group, they are assigned User role in Puddle.auth.awsCognito.implicitGrant
should be true/false and is false by default. If true, then users are allowed access to Puddle (using user role) even if they are not members of Administrators nor Users group. If false, then users must be members of at least one group to be allowed access to Puddle.auth.ldap.enabled
should be true/false and is false by default. If true, then authentication using LDAP is enabled.auth.ldap.host
should be the LDAP server hostname.auth.ldap.port
should be the port where LDAP is accessible, defaults to 389.auth.ldap.baseDN
should be the BaseDN where authentication search will start.auth.ldap.baseDNGroup
should be the BaseDN where search for user’s group will start.auth.ldap.bindDN
should be the BindDN used by Puddle to query LDAP.auth.ldap.bindPassword
should be the password of the user used by Puddle to query LDAP.auth.ldap.implicitGrant
should be true/false and is false by default. If true, then users are allowed access to Puddle (using user role) even if they are not members of Administrators nor Users group. If false, then users must be members of at least one group to be allowed access to Puddle.auth.ldap.adminsGroup
should be the name of the Administrators group. Users in this group are assigned Administrator role in Puddle, users in Administrators group and Users group are considered Administrators.auth.ldap.usersGroup
should be the name of the Users group. Users in this group are assigned User role in Puddle, users in Administrators group and Users group are considered Administrators.packer.path
should point to the packer binary. Defaults to/opt/h2oai/puddle/deps/packer
.packer.usePublicIP
should be true/false and is true by default. If true then packer will use public IP to communicate with the provisioned Virtual machines, otherwise private IP will be used.terraform.path
should point to the terraform binary. Defaults to/opt/h2oai/puddle/deps/terraform
.terraform.usePublicIP
should be true/false and is true by default. If true then terraform will use public IP to communicate with the provisioned Virtual machines, otherwise private IP will be used.backend.baseUrl
should be the URL where Puddle is running, for example https://puddle.h2o.ai.backend.connections.usePublicIp
should be true/false and is true by default. If true then backend will use public IP to communicate with the provisioned Virtual machines, otherwise private IP will be used.webclient.usePublicIp
should be true/false and is true by default. If true then public IP is shown in UI, otherwise private IP is displayed.providers.azure.enabled
should be true/false and is false by default. If true then Microsoft Azure is enabled as provider in Puddle. All variables underproviders.azure
must be set if enabled.providers.azure.authority
should be set tohttps://login.microsoftonline.com/<Azure ActiveDirectory Name>.onmicrosoft.com
.
- The Azure Active Directory name can be found in following way:
- Go to Azure Active Directory blade.
- Select Overview.
providers.azure.location
should be set to the same value that was specified for the Resource group, for exampleeastus
.providers.azure.rg
should be set to the name of the newly created Resource group.providers.azure.vnetrg
should be set to the name of the Resource group where VNET and Subnet are present.providers.azure.vnet
should be set to the id of the newly created Virtual network.providers.azure.sg
should be set to the id of the newly created Network security group.providers.azure.subnet
should be set to the id of the newly created Subnet.providers.azure.enterpriseApplicationObjectId
should be the Object ID of the Enterprise Application.
- The Enterprose Application Object ID can be found in following way:
- Go to the Azure Active Directory blade.
- Select Enterprise Applications.
- Select the newly created Enterprise Application.
- Use the Object ID.
providers.azure.adminRoleId
should be set to the ID of the newly created Administator Role in the Application Registration Manifest.
- The Administator Role ID can be found in following way:
- Go to the Azure Active Directory blade.
- Select App registrations (preview).
- Select the newly created App registration.
- Select Manifest.
- Search for Administator role under appRoles and use the ID of this role.
providers.azure.publicIpEnabled
should be true/false and is true by default. Public IP is created if and only if this is set to true. Must be set to true if at least one of packer, terraform, backend or webclient uses public IP.providers.azure.packerInstanceType
should be the instance type used by Packer to build images. Defaults to Standard_DS2_v2.providers.aws.enabled
should be true/false and is false by default. If true then Amazon AWS is enabled as provider in Puddle. All variables underproviders.aws
must be set if enabled.providers.aws.owner
should be the owner of the newly created resources.providers.aws.vpcId
should be the ID of the VPC where Virtual machines will be launched.providers.aws.sgId
should be the ID of the Security Group applied to provisioned Virtual machines.providers.aws.subnetId
should be the ID of the Subnet where Virtual machines will be placed.providers.aws.publicIpEnabled
should be true/false and is false by default. If true, then no public IP will be assigned. Must be set to true if at least one of packer, terraform, backend or webclient uses public IP.providers.aws.packerInstanceType
should be the instance type used by packer to build images, defaults to m5.large.products.dai.configTomlTemplatePath
should be the path to custom config.toml file, which will be used as default configuration for all new Driverless AI Systems. If not set, the default file is used.products.dai.license
should be the path to DriverlessAI license file. If set, then this license will be automatically installed on all provisioned systems.logs.dir
should be set to a directory where logs should be placed.logs.maxSize
should be the max size of log file, in MB, defaults to 1000.logs.maxBackups
should be the number of old files retained, defaults to 15.logs.maxAge
should be the max age of retained files, in days, defaults to 60. Older files are always deleted.logs.compress
should be true/false and is true by default. If true then the files will be compressed when rotating.mailing.enabled
should be true/false. If true then mailing is enabled. All fields undermailing
are mandatory if this is set to true.mailing.server
should be the hostname and port of the SMTP server, for example smtp.example.com:587.mailing.username
should be the client username.mailing.password
should be the client password.mailing.fromAddress
should be the email address used as FROM, for example in case of an address ‘<Puddle> puddle@h2o.ai’ this field should be set to puddle@h2o.ai.mailing.fromName
should be the name used as FROM, defaults to Puddle, for example in case of an address ‘<Puddle> puddle@h2o.ai’ this field should be set to Puddle.mailing.recipients
should be the space-separated list of recipients.mailing.offsetHours
should be a number of hours between repeated email notifications, defaults to 24, does not apply to FAILED system notifications.
Configuring Environment Variables¶
The next step is to to fill in the variables in EnvironmentFile file, which is located at /etc/puddle/EnvironmentFile
. The EnvironmentFile should contain the following:
# Should point to dir with config.yaml
PUDDLE_CONFIG_DIR='/etc/puddle/'
ARM_SKIP_PROVIDER_REGISTRATION=true # AzureRM Provider should skip registering the Resource Providers
# Azure related environment variables, please fill-in all values if you use Azure as provider
# AZURE_SUBSCRIPTION_ID='YOUR-SUBSCRIPTION-ID'
# AZURE_TENANT_ID='YOUR-TENANT-ID'
# AZURE_CLIENT_ID='YOUR-CLIENT-ID'
# AZURE_CLIENT_SECRET='YOUR-CLIENT-SECRET'
# AWS related environment variables, please fill-in all values if you use AWS as provider
# AWS_ACCESS_KEY_ID='YOUR-AWS-ACCESS-KEY-ID'
# AWS_SECRET_ACCESS_KEY='YOUR-AWS-SECRET-ACCESS-KEY'
# AWS_REGION='AWS-REGION'
PUDDLE_CONFIG_DIR
directory where the config.yaml file is present.ARM_SKIP_PROVIDER_REGISTRATION
- AzureRM Provider should skip registering the Resource Providers. This should be left as true.AZURE_SUBSCRIPTION_ID
is the ID of the subscription that should be used.- This value can be found in following way:
- Search for Subscriptions.
- Use the SUBSCRIPTION ID of the subscription you want to use.
- This value can be found in following way:
AZURE_TENANT_ID
is ID of tenant that should be used.- This value can be found in following way:
- Select Azure Active Directory blade.
- Select App registrations (preview).
- Select the newly created App registration.
- Use Directory (tenant) ID.
- This value can be found in following way:
AZURE_CLIENT_ID
is the Application ID that should be used.- This value can be found in following way:
- Select Azure Active Directory blade.
- Select App registrations (preview).
- Select the newly created App registration.
- Use Application (client) ID.
- This value can be found in following way:
AZURE_CLIENT_SECRET
client secret that should be used.- This value can be found in following way:
- Select the Azure Active Directory blade.
- Select App registrations (preview).
- Select the newly created App registration.
- Select Certificates & Secrets.
- Click New client secret.
- Fill in the form and click Add.
- The secret value should be visible. Copy it because after refreshing the page, this value is gone and cannot be restored.
- This value can be found in following way:
AWS_ACCESS_KEY_ID
AWS Access Key Id used by Puddle to access the AWS services.AWS_SECRET_ACCESS_KEY
AWS Secret Access Key used by Puddle to access the AWS services.AWS_REGION
AWS Region used by Puddle to access the AWS services.
Running Puddle¶
After all of the previous steps are successfully completed, we can now start Puddle. Execute the following command to start the server and web UI:
systemctl start puddle
Puddle is accessible on port 443 if HTTPS is enabled, or on port 80 if HTTP is being used.
First Steps¶
At first, you will have to perform some initialization steps:
- Log in to Puddle as the Administrator.
- Go to Administration > Check Updates.
- Either use the update plan from the default URL location, or specify a custom update plan file.
- Click Submit.
- Review the plan and click Apply.
- Go to Administration > Images.
- Build all the images you want to use. Please be aware this can take up to 1 hour.
Once the images are built, your Puddle instance is ready.
Stats Board (Optional)¶
The stats board is an optional component. It’s distributed as Python wheel, and it requires Python 3.6. It’s recommended (although not necessary) to run the board inside a virtual environment.
Use the following to install the required dependencies:
apt install gcc libpq-dev python3.6-dev python-virtualenv
yum install epel-release
yum install gcc postgresql-devel python36-devel python-virtualenv
Use the following to create the virtualenv:
mkdir -p /opt/h2oai/puddle/envs
cd /opt/h2oai/puddle/envs
virtualenv -p python3.6 puddle-stats-env
Please make sure that the virtualenv uses the same name and is available at the same path as in this provided snippet. Otherwise the systemd script used to manage Stats Board will not work.
Use the following to install the stats board. Please note that this command will install dependencies as well:
source /opt/h2oai/puddle/envs/puddle-stats-env/bin/activate
pip install puddle_stats_board-<VERSION>-py3-none-any.whl
Use the following to run the stats board:
systemctl start puddle-dashboard
The stats board is running on port 8050 and is accessible from Puddle UI at http://<PUDDLE_SERVER_ADDRESS>/board. There is a link in the Administration menu as well.