Creating a Self Managed Commerce Database Server
Each Self Managed Commerce environment requires a dedicated database. This topic guides you through the options to create the database service that will host the Self Managed Commerce database.
Introduction
There are four strategies you can use for creating the Self Managed 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. Data saved in a containerized database is lost when the container is deleted.
- Alternatively, during development, create a single AWS Aurora RDS Database and create separate databases on that server. Ensure that you use different database names for each Self Managed Commerce deployment and developer.
- For staging and production, create a separate AWS Aurora RDS Database for each deployment.
- Using an existing schema in an existing external compatible database.
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 creating 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
To create an AWS Aurora RDS MySQL Database cluster, run the create-or-delete-mysql-server job in Jenkins with the following parameters:
deleteServeruseLTSVersionauroraEngineVersionencryptDatabaseencryptionKeypreventKeyDeletionbackupRetentionDaysbackupWindowPreferencedbInstanceClassenableAuditLoggingcloudOpsForKubernetesRepoURLcloudOpsForKubernetesBranchkubernetesNicknameclusterName
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.r5.xlarge, each of which has 4 vCPUs and 32 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.
Parameters for the create-or-delete-mysql-server Jenkins Job
applyImmediately
This parameter only works if you change either the RDS instance class or the RDS engine version.
Set this parameter to true to immediately have any specified changes to the RDS Aurora instance class or engine version applied.
:::Warning
The database instance and any Self Managed Commerce services that rely on the database instance will be unavailable while the changes are applied.
:::
Ensure that you set this parameter to true if you are making changes to the engine version. You cannot make changes to the engine version using this Jenkins job if the parameter is set to false. This is due to a limitation of the AWS Terraform provider implementation.
Set this parameter to false if you want to make changes to the instance class without downtime. Those changes will apply during the next RDS maintenance window.
Note
Engine version upgrades may still be applied without downtime in the RDS maintenance windows if you do the engine version upgrade in the AWS RDS console. If you follow that approach, you must ensure that those changes have been completed entirely before running this job.
enablePerformanceInsights
When you set this parameter to true, you enable the free tier of the Amazon Performance Insights database performance tuning and monitoring feature for the two instances created.
deleteServer
Deletes the server instead of creating it.
useLTSVersion
This parameter ensures the validation of the dbInstanceClass parameter against Long Term Support (LTS) versions of Aurora MySQL.
If you are using non-LTS versions of the Aurora engine, set this parameter to false.
This is used when running a high performance configuration of Self Managed Commerce on Arm-based AWS Graviton2 processor instance types specified in the dbInstanceClass Jenkins job parameter.
auroraEngineVersion
If the useLTSVersion Jenkins job parameter is set to false, use this version of Aurora engine instead.
This is used when running a high performance configuration of Self Managed Commerce on Arm-based AWS Graviton2 processor instance types specified in the dbInstanceClass Jenkins job parameter.
encryptDatabase
Optional. When selected, the RDS database uses at rest encryption.
encryptionKey
Optional. If encryptDatabase or enableAuditLogging is set to true, you can provide the Amazon Resource Name of a custom AWS Key Management Service key. A KMS key is generated 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.
backupRetentionDays
The number of days that Amazon Aurora retains restore data. The number of days can be from 1 to 35. Amazon Aurora backs up your cluster volume automatically and retains restore data for the length of the backup retention period.
For more information about the backup retention days, see Overview of backing up and restoring an Aurora DB cluster.
backupWindowPreference
Specify a preferred backup window using a 24-hour clock. The window should be a period of at least 30 minutes, such as 11:00-13:00. If you do not want to specify a preferred backup window, leave the parameter value as AmazonsDefault. Amazon Aurora assigns a default 30-minute backup window.
For more information about the backup window, see Overview of backing up and restoring an Aurora DB cluster.
dbInstanceClass
note
The Amazon Aurora DB instance class does not immediately change when you update this value for an existing Aurora RDS MySQL cluster. Instead, the change is applied in the next maintenance window. You can see the scheduled changes in your RDS cluster in the Amazon RDS console by clicking the "Maintenance & backups" tab.
Specify the Amazon Aurora DB instance class to use. Choose a DB instance class that meets your processing power and memory requirements. The value must be a valid Aurora instance class that is available in your AWS region. The smallest supported option is db.r5.xlarge.
For more information on the available instance classes, see DB instance classes.
enableAuditLogging
When selected, Amazon Aurora advanced auditing is enabled, and audit data is captured in Amazon CloudWatch. KMS based encryption of CloudWatch logs for the database logs group will be turned on. You can provide the ARN of a custom KMS key in encryptionKey. A KMS key is generated if you do not provide one.
note
If you are providing a custom KMS key ensure that the RDS log group has permission to use the key. For more information, see Set Permissions on the Key.
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 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, be certain 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 Self Managed 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 Self Managed 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.
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. Find the hostname in the Amazon RDS web console. The format is similar to sample-database.cluster-asdf.us-west-2.rds.amazonaws.com.
TF_VAR_database_username
The database user that the Self Managed 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 Self Managed 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.