Creating an Elastic Path Commerce Database Server
Each Elastic Path Commerce environment requires a dedicated database. This topic guides you through the options to create the database service that will host the Elastic Path Commerce database.
Introduction
There are four strategies you can use for creating the Elastic Path Commerce database service using CloudOps for Kubernetes:
- During development, use the MySQL Docker image to deploy a non-production database server that runs in a container
- Alternatively, during development, create a single Azure Database for MySQL server or an AWS Aurora RDS Database and create separate databases on that server. Ensure that you use different database names for each Elastic Path Commerce deployment and developer.
- For staging and production, create a separate Azure Database for MySQL server or an AWS Aurora RDS Database for each deployment. The type of database depends on which cloud provider you selected during the bootstrap process.
- Using an existing schema in an existing external database from an Elastic Path Commerce deployment on CloudOps for AWS.
These strategies are all automated by CloudOps for Kubernetes by Jenkins jobs.
Creating Containerized MySQL Server
warning
This method of running a MySQL server is not production-grade. For more information about a suitable approach for production, see the Creating a Cloud Database Server section.
To create a containerized MySQL server, run the
create-or-delete-mysql-containerjob with the following parameters:deleteContainercloudOpsForKubernetesRepoURLcloudOpsForKubernetesBranchkubernetesNicknameimageTagclusterName
The job creates a container running MySQL 5.7 within the Kubernetes namespace specified by kubernetesNickname.
The username and password are randomly generated and stored in a Kubernetes Secret, in the same Kubernetes namespace.
The Kubernetes Service created for the MySQL server is of ClusterIP type and there is no Ingress for it. By default, the MySQL container is only accessible from other containers in the same namespace.
Parameters for the create-or-delete-mysql-container Jenkins Job
deleteContainer
When this parameter is selected, the specified MySQL service and resources, including the container, will be deleted instead of created.
cloudOpsForKubernetesRepoURL
The URL to your hosted copy of the cloudops-for-kubernetes Git repository.
cloudOpsForKubernetesBranch
The branch of the cloudops-for-kubernetes Git repository to use during the deployment.
kubernetesNickname
This job uses the value of kubernetesNickname as the Kubernetes namespace where the MySQL container is created and connection information is saved as secrets. If the namespace does not exist, this job creates it. To be compatible with Terraform, Kubernetes, and DNS domain name requirements, ensure that the kubernetesNickname is lowercase and alphanumeric. When you deploy the Elastic Path stack that will use this MySQL container, be certain to specify the same value for kubernetesNickname.
If you specify a value where a MySQL container is already deployed, then that MySQL container will be updated and may be replaced and data lost.
imageTag
The tag of the mysql Docker image to use.
clusterName
The name of the Kubernetes cluster in which to deploy the MySQL service.
Creating a Cloud Database Server
In AWS, you can use the create-or-delete-mysql-server job to provision an AWS Aurora RDS MySQL Database cluster. In Azure, you can use the same create-or-delete-mysql-server job to provision an Azure Database for MySQL server.
Creating an Aurora RDS MySQL Database cluster
To create an AWS Aurora RDS MySQL Database cluster, run the create-or-delete-mysql-server job in Jenkins with the following parameters:
deleteServerencryptDatabaseencryptionKeypreventKeyDeletioncloudOpsForKubernetesRepoURLcloudOpsForKubernetesBranchkubernetesNicknameclusterName
The job creates an Aurora RDS MySQL cluster with a default and standby node on the Private subnets that were created along with your EKS cluster. By default, each node is a db.t3.medium, each of which has 2 vCPUs and 4 GB RAM. The server is running MySQL 5.7 and is configured for geo-redundant daily backups that are preserved for 14 days. The KubernetesNickname parameter should be unique across your AWS account to avoid conflicts in database server naming.
The username and password are randomly generated and stored in a Kubernetes Secret.
The job sets the server settings:
character_set_server=UTF8MB4
tx_isolation=READ-COMMITTED
max_connections=1000
This Job also creates a new RDS security group that allows access to the database from within the VPC that was created along with the EKS cluster.
Creating an Azure database for MySQL server
To create an Azure Database for MySQL server, run the create-or-delete-mysql-server job in Jenkins with the following parameters:
deleteServercloudOpsForKubernetesRepoURLcloudOpsForKubernetesBranchkubernetesNicknameclusterName
The job creates a server within the same node resource group as the AKS cluster. By default, the server is a GP_Gen5_4 SKU, which translates to 4 cores with 5 GB RAM per core. It also has 1048576 MB of storage that Azure provides IOPS based on storage size, and this translates to 3000 IOPS. The server is running MySQL 5.7 and has geo-redundant backups for seven days. The kubernetesNickname parameter must be unique across your Azure subscription to avoid conflicts in database server naming.
The username and password are randomly generated and stored in a Kubernetes Secret.
The following settings in the server are set in this job:
character_set_server=UTF8MB4
tx_isolation=READ-COMMITTED
wait_timeout=5400
The job also sets the VNet rules for the server to only allow access from the Kubernetes cluster.
Parameters for the create-or-delete-mysql-server Jenkins Job
deleteServer
Deletes the server instead of creating it.
encryptDatabase
Optional. When selected, the RDS database uses at rest encryption.
encryptionKey
Optional. If encryptDatabase is set to true you can provide the ARN (Amazon Resource Name) of an existing custom KMS (Key Management Service) key. A KMS key is generated by the job if one is not provided.
preventKeyDeletion
Optional. Select this parameter if you are deleting your MySQL server and want to ensure that your generated KMS key will not be deleted. If you have database snapshots or backups of the MySQL server created by this job that you need to read in the future, you might need the KMS key. This parameter is only run when deleteServer is selected.
cloudOpsForKubernetesRepoURL
The URL to your hosted copy of the cloudops-for-kubernetes Git repository.
cloudOpsForKubernetesBranch
The branch of the cloudops-for-kubernetes Git repository to use during the deployment.
kubernetesNickname
This job uses the value of kubernetesNickname as the Kubernetes namespace where the database connection information is stored, and in the name of the database server. If the namespace does not exist, this job creates it. To be compatible with Terraform, Kubernetes, and DNS domain name requirements, ensure that the kubernetesNickname is lowercase and alphanumeric.
The kubernetesNickname value must be unique across your Azure subscription or AWS account to avoid conflicts in database server naming. If you specify a value used by an existing database service, then the configuration of that service will be updated.
When you deploy the Elastic Path stack that will use this MySQL server, ensure to specify the same value for kubernetesNickname.
clusterName
The name of the Kubernetes cluster that will store database connection information. To use a MySQL server created by this job an Elastic Path stack must be deployed in the same Kubernetes cluster. |
Using an Existing Schema
You can use an existing schema in an existing external database if that schema is for the correct Elastic Path Commerce version, and if the database instance is accessible to services running in the Kubernetes cluster.
To allow an Elastic path Commerce stack in CloudOps for Kubernetes to use an existing database and schema, run the Jenkins job create-or-delete-database-and-user-in-external-database-instance. This creates the necessary Kubernetes secrets that the Elastic Path Commerce stack will use to attempt to connect to the external database instance.
For information on migrating a database from CloudOps for AWS to CloudOps for Kubernetes, see Migrating a Database from CloudOps for AWS to CloudOps for Kubernetes.
Parameters for the create-or-delete-database-and-user-in-external-database-instance Jenkins Job
deleteDatabase
When checked, this deletes the Kubernetes secrets instead of creating them. Must be run with values in TF_VAR_kubernetes_nickname, TF_VAR_database_name, TF_VAR_database_username, and TF_VAR_database_password.
TF13Update
warning
Do not set this parameter to true if you are running this job on an existing database instance for the first time. This parameter only updates previous runs of this job.
If you are updating from CloudOps for Kubernetes v2.5.x, set to true. When true, updates an existing external database resource to be compatible with Terraform v0.13.
target_subscription_id
(Azure Only) The ID of the subscription group the external database instance is in.
TF_VAR_target_resource_group
(Azure Only) The resource group the external database instance is in.
TF_VAR_use_existing_schema
When checked, if the external database instance has an existing schema, the job will not create a new schema and user. The job instead uses the values provided in TF_VAR_database_name, TF_VAR_database_username, and TF_VAR_database_password.
TF_VAR_database_name
The name of the schema in the external database. For a Commerce deployment TF_VAR_use_existing_schema should be true. The schema name provided must already exist and have valid user credentials. These values will be used in this job instead of creating new ones.
If TF_VAR_use_existing_schema is false, the job creates a schema with this name. In this case this parameter can also be left blank and the job generates a schema name.
TF_VAR_root_username
The root username of the external database instance. This can be found in the Kubernetes secret created by the create-or-delete-mysql-server job or in the CloudOps for AWS Consul config store.
TF_VAR_root_password
The root password of the external database instance. This can be found in the Kubernetes secret created by the create-or-delete-mysql-server job or in the CloudOps for AWS Consul config store.
TF_VAR_database_hostname
The name of the external database instance. Use the serverName parameter if created by the job create-or-delete-mysql-server or the DB cluster id of an RDS instance if created by a CloudOps for AWS Author and Live environment.
TF_VAR_database_server_url
The hostname of the server to connect to. This can be found in the web console of your cloud provider. For example, an Amazon RDS cluster endpoint would have the format sample-database.cluster-asdf.us-west-2.rds.amazonaws.com. An Azure MySQL server endpoint is the server name with the format sample-database.azure.database.azure.com.
TF_VAR_database_username
The database user that the Elastic Path Commerce stack should use when connecting to the MySQL database. The username is automatically created if there is no value given or the given username does not exist in the database instance. Do not use the same value as TF_VAR_root_username.
TF_VAR_database_password
The database password that the Elastic Path Commerce stack should use when connecting to the MySQL database. The password is automatically created if the given username does not exist in the database instance. Do not use the same value as TF_VAR_root_password.
TF_VAR_kubernetes_nickname
The Kubernetes namespace where the database credentials and connectivity information will be stored as Kubernetes secrets. The Elastic Path stack that will use the existing database schema must be deployed with the same nickname. The nickname must be lower-case and alphanumeric to be compatible with Terraform, Kubernetes workspace, and DNS domain name requirements.
cluster_name
The name of the Kubernetes cluster where the Kubernetes secrets should be created.
Ensure this cluster matches the cluster where you will deploy the Commerce stack. This job creates a Kubernetes Secret that the Commerce stack will need access to.
cloudops_for_kubernetes_branch
The CloudOps for Kubernetes branch to use for the job to clone the Jenkinsfile and Terraform configuration. This defines how to deploy the infrastructure.