Instructional Guide for Project Configuration¶

This guide will walk you through configuring the conf/project.yaml file, including settings for project, AWS, VPC, and OpenSearch. It is divided into three sections: Getting Started, Parameter Definitions, and Examples for easy reference.

Getting Started¶

Follow these steps to configure your YAML configuration file:

Step 1: Configure Project Settings¶

Replace your-project-name with your actual project name.

project_name: your-project-name  # Replace 'your-project-name' with the name of your project.

Step 2: Configure AWS Settings¶

Specify the AWS region where your resources will be deployed using region_name.

aws:
  region_name: ap-northeast-1  # AWS region where resources will be deployed. Modify if needed (e.g., 'ap-northeast-1').

Step 3: Configure VPC Settings¶

Specify the value for the vpc_id field.

vpc:
  vpc_id: your-vpc-id  # Replace 'your-vpc-id' with the ID of your existing VPC.

Step 4: Configure OpenSearch Settings¶

The instructions on OpenSearch settings are divided into three parts: settings for OpenSearch itself, authentication settings, and auto scaling settings.

OpenSearch¶

Specify the values for the domain and domain_name fields.

opensearch:
  domain: your-opensearch-domain  # Replace 'your-opensearch-domain' with the domain VPC endpoint for OpenSearch.
  domain_name: your-opensearch-domain-name  # Replace 'your-opensearch-domain-name' with the specific domain name.

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  # auth:
  #   type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
  #   master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch Auto Scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  # auto_scaling:
  #   min_instance_count: 2  # Minimum number of instances for auto scaling.
  #   max_instance_count: 12  # Maximum number of instances for auto scaling.
  #   scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
  #   scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.

Authentication¶

If the fine-grained access control in your OpenSearch is enabled, provide the necessary information in the auth section:

Specify the type of authentication in the type field. Supported types include:
aws: Use AWS IAM authentication.
basic: Use the account and password retrieved from AWS Secrets Manager or AWS Systems Manager Parameter Store.
Enter the Amazon Resource Name (ARN) of the authentication in the master_user_secret_arn field.

opensearch:
  domain: your-opensearch-domain  # Replace 'your-opensearch-domain' with the domain VPC endpoint for OpenSearch.
  domain_name: your-opensearch-domain-name  # Replace 'your-opensearch-domain-name' with the specific domain name.

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  auth:
    type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
    master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  # auto_scaling:
  #   min_instance_count: 2  # Minimum number of instances for auto scaling.
  #   max_instance_count: 12  # Maximum number of instances for auto scaling.
  #   scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
  #   scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.

If the fine-grained access control in your OpenSearch is disabled, comment out the auth section.

opensearch:
  domain: your-opensearch-domain  # Replace 'your-opensearch-domain' with the domain VPC endpoint for OpenSearch.
  domain_name: your-opensearch-domain-name  # Replace 'your-opensearch-domain-name' with the specific domain name.

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  # auth:
  #   type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
  #   master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  # auto_scaling:
  #   min_instance_count: 2  # Minimum number of instances for auto scaling.
  #   max_instance_count: 12  # Maximum number of instances for auto scaling.
  #   scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
  #   scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.

Auto Scaling¶

If you want to add the auto scaling service to your OpenSearch, provide the necessary information in the auto_scaling section:

Specify the values for the min_instance_count, max_instance_count, scale_down_cpu_util_threshold and scale_up_cpu_util_threshold fields.

opensearch:
  domain: your-opensearch-domain  # Replace 'your-opensearch-domain' with the domain VPC endpoint for OpenSearch.
  domain_name: your-opensearch-domain-name  # Replace 'your-opensearch-domain-name' with the specific domain name.

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  # auth:
  #   type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
  #   master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  auto_scaling:
    min_instance_count: 2  # Minimum number of instances for auto scaling.
    max_instance_count: 12  # Maximum number of instances for auto scaling.
    scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
    scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.

If you don't want to use the auto scaling service for your OpenSearch, comment out the auto_scaling section.

opensearch:
  domain: your-opensearch-domain  # Replace 'your-opensearch-domain' with the domain VPC endpoint for OpenSearch.
  domain_name: your-opensearch-domain-name  # Replace 'your-opensearch-domain-name' with the specific domain name.

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  # auth:
  #   type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
  #   master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  # auto_scaling:
  #   min_instance_count: 2  # Minimum number of instances for auto scaling.
  #   max_instance_count: 12  # Maximum number of instances for auto scaling.
  #   scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
  #   scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.

Step 5: Saving Configuration¶

Save your YAML file after filling in the necessary information.

Parameter Definitions¶

Parameter	Data Type	Required	Description
`project_name`	String	Required	The name of your project.
`aws.region_name`	String	Required	AWS region where resources will be deployed (e.g., 'ap-northeast-1').
`vpc.vpc_id`	String	Required	ID of the existing VPC.
`opensearch.domain`	String	Required	The domain VPC endpoint for OpenSearch.
`opensearch.domain_name`	String	Required	The domain name for OpenSearch.
`opensearch.auth.type`	String	Optional	Type of authentication. Options: `aws` for IAM roles or `basic` for account and password.
`opensearch.auth.master_user_secret_arn`	String	Optional	The ARN associated with the authentication.
`opensearch.auto_scaling.min_instance_count`	Int	Optional	Minimum number of instances for auto scaling.
`opensearch.auto_scaling.max_instance_count`	Int	Optional	Maximum number of instances for auto scaling.
`opensearch.auto_scaling.scale_down_cpu_util_threshold`	Int	Optional	CPU utilization threshold to scale down instances.
`opensearch.auto_scaling.scale_up_cpu_util_threshold`	Int	Optional	CPU utilization threshold to scale up instances.

Examples¶

Example 1: Configuration for Using Opensearch Authentication and Auto Scaling¶

##  You can configure the project name.
project_name: project-book


##  You can configure the AWS region.
aws:
  region_name: us-west-2


##  You need to use the existing VPC.
vpc:
  vpc_id: vpc-0abc1234def567890


##  You need to use the existing OpenSearch.
opensearch:
  domain: vpc-opensearch-book-abcdefgh1ijklm2ln34opqr5st.us-west-2.es.amazonaws.com
  domain_name: book

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  auth:
    type: basic
    master_user_secret_arn: arn:aws:ssm:us-west-2:123456789012:parameter/opensearch-aws-authentication

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  auto_scaling:
    min_instance_count: 1  # Minimum number of instances for auto scaling.
    max_instance_count: 10  # Maximum number of instances for auto scaling.
    scale_down_cpu_util_threshold: 25  # CPU utilization threshold to scale down instances.
    scale_up_cpu_util_threshold: 75  # CPU utilization threshold to scale up instances.

Example 2: Configuration for Not Using Opensearch Authentication and Auto Scaling¶

##  You can configure the project name.
project_name: project-book


##  You can configure the AWS region.
aws:
  region_name: us-west-2


##  You need to use the existing VPC.
vpc:
  vpc_id: vpc-0abc1234def567890


##  You need to use the existing OpenSearch.
opensearch:
  domain: vpc-opensearch-book-abcdefgh1ijklm2ln34opqr5st.us-west-2.es.amazonaws.com
  domain_name: book

  ##  If the fine-grained access control in your OpenSearch is enabled,
  ##  provide the necessary information in the 'auth' section as required.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auth' section.
  # auth:
  #   type: aws  ##  The authentication type. Options: `aws` for AWS IAM authentication or `basic` for account and password. If `basic` is selected, you need to provide master_user_secret_arn.
  #   master_user_secret_arn: auth-arn  # The ARN of the SSM Parameter Store or AWS Secrets Manager where the master user’s account and password information is stored.

  ##  You can build OpenSearch auto scaling mechanism by configuring the auto_scaling section.
  ##  By default, this setting is disabled. To enable it, uncomment the 'auto_scaling' section.
  # auto_scaling:
  #   min_instance_count: 2  # Minimum number of instances for auto scaling.
  #   max_instance_count: 12  # Maximum number of instances for auto scaling.
  #   scale_down_cpu_util_threshold: 30  # CPU utilization threshold to scale down instances.
  #   scale_up_cpu_util_threshold: 80  # CPU utilization threshold to scale up instances.