Skip to content

sbe-parameter-values.md

Latest commit

 

History

History
71 lines (60 loc) · 8.74 KB

sbe-parameter-values.md

File metadata and controls

71 lines (60 loc) · 8.74 KB

StartingBlocks Deployment Parameters

There are a large amount of parameter values needed in order to deploy a properly configured StartingBlocks environment. Some are self-explanatory and others might need additional description or guidance. Below is a list of parameters with some additional context. Users can expect descriptions, values, and parameters to change over time as the maintainers make improvements and accomodations to the codebase.

Parameters

  • Stack name - Name your stack something unique and related to your environment.

General Information

  • EnvLabel - Unique name for your environment. Generally will align with the Stack name and be included in your S3 source bucket name.
  • HostedZoneId - The route 53 Hosted Zone that was created as a prerequisite to deploying StaritingBlocks.
  • DomainName - Fully qualified domain name to create wild card certificate for. StartingBlocks uses a wildcard certificate in order to better track api clients in logs.
  • Partner - The StartingBlocks product team uses this parameter to keep track of partner deployments. It is used to generate unique resource names for deployed resources.

Versions and Features

  • EdFiApiVersion - The version of the Ed-Fi API to be deployed.
  • DataStandardVersion - The version of the Ed-Fi Data Standard to be deployed. Note that not all data standard versions are supported by all Ed-Fi Api versions.
    EdFiApiVersion Supported DataStandardVersion
    7.1 DS4, DS5
    7.2 DS4, DS5.1
    7.3 DS4, DS5.2
  • PostgresVersion - Choose the version of Postgres to use for Aurora RDS. These versions have been tested and used by the StartingBlocks team. Versions outside of this list have not been tested.
  • AdminInterface - Currently only two options are available. Ed-Fi Admin Api or None.
  • DeploySwagger - Optionally will deploy a swagger site for the StartingBlocks environment.
  • APIPublisher - If users intend for the environment to be used for publishing with the API publisher, set this to true to support snapshots with Aurora clones.

Deployment Files

  • S3SourceBucket - The name of the S3 bucket in which StartingBlocks templates are sourced. This is the bucket you created in Step 1 of the deployment steps.
  • ArtifactsS3SourceBucket - Determines if the deployment should use EA's central artifact store (available in all US regions), or look for custom artifacts in the cloudformation bucket named above.
  • WebApiZipFile - To use the default Api build as offered through EA's central artifact store, leave value as default. If you have a custom build of the Ed-Fi Api, construct the application zip file, and drop it in the docker folder in the S3 bucket created in Step 1. Place the name of the custom build zip file in this field if you want to deploy the custom Api.
  • DatabaseArtifact - To use the default database artifacts as offered through EA's central artifact store, leave the value as default. If you have custom database artifacts, upload custom artifacts to the database folder in the S3 bucket created in Step 1. Place the unique identifier for the database artifacts here.

Note

Each database artifact in the database folder is prefixed with which database it is. i.e. EdFi_Ods_Minimal_Template and EdFi Ods_Populated_Template for the ODS, EdFi_Security for the security database, and EdFi_Admin for the admin database. If uploading a custom build, the prefixes must stay the same, but the suffix can change, and that is what should be used as the DatabaseArtifact parameter value if using custom database builds. i.e. EdFi_Ods_Minimal_Template_71_patch2_20240505.sql. The value to be populated for DatabaseArtifact would be 71_patch2_20240505. Note that users must have the same suffix for all database artifacts, i.e. the ods, the security and admin databases that are to be deployed must all use the same suffix.

Ed-Fi Options

  • EdFiTenancyMode - Defines configuration for Ed-Fi API/ODS. SingleTenant or MultiTenant.
  • DatabaseData - Minimal or Populated. Minimal deploys an ODS with only the Ed-Fi default descriptors and nothing else. Populated deploys an ODS with the Grand Bend test data set. Minimal is what should be used for production deployments. This parameter only affects SingleTenant mode deployments. In SingleTenat deployments a default ODS is created as part of the CloudFormation process, and this parameters selects the template to use. In MultiTenant deployments both templates are imported and available to create ODSs later as needed.
  • BearerTokenPerClientLimit - Introduced in Ed-Fi 7.3, this setting controls the maxium number of tokens that can be issued per client, within the span of a token lifetime.

Capacity and Scaling

  • EnvironmentSize - Choose the size of your resources. This parameter informs both the EC2 instance types deployed in the Auto Scaling Group and the database instance type for RDS.
  • WebAPIMinInstances - The minimum number of EC2 instances managed by the Auto Scaling Group.
  • WebAPIMaxInstances - The maximum number of EC2 instances managed by the Auto Scaling Group.
  • SpotFleetPercentage - The percentage of On-Demand Instances as part of additional capacity that your Auto Scaling Group provisions.
  • DatabaseType - Provisioned or Serverless Aurora. Serverless will provide real time scaling, but costs more to host.
  • DeployReplica - Will deploy a read replica in RDS. If users anticipate a large amount of reads on the system, it might be advisable to deploy a read replica.
  • WebAPIMaxPoolSize - Maximun pool size for connections to the Ed-Fi ODS database. This is per database.
  • WebAPIConnectionIdleLifetime - Connection idle lifetime for connections to the Ed-Fi ODS database.

Security Options

  • SSLPolicy - Policy to determine which ssl/tls ciphers are accepted.
  • AdminApiCIDRs - List of CIDRs to allow access to call Admin API. It's advisable to add the CIDR for a user's office or locations where administration of the environment will need to be acccessible.
  • AdminAccountIds - StartingBlocks utilizes many management functions deployed as AWS Lambda functions. If users would like to reach these functions from another AWS account, users can input their AWS account IDs here. This will allow the management Lambda functions to be called cross account.
  • WebACLArn - Optionally attach a WAF (deployed separately) via ARN to the API load balancer.
  • SSHServerParentStack - Optionally associate SSH server to StartingBlocks resources. SSH server is deployed separately.

Monitoring and Alerting

  • S3AccessLogBucket - Optionally store Elastic Load Balancer access logs in the S3 bucket named here.
  • SNSTopicArn - Optionally add ARN of SNS topic to publish Route53 HealthCheck Alarms. SNS topic is deployed separately.
  • SlackWebhookUrl - Optionally add a slack webhook URL to surface alerts from Beanstalk and RDS environments.

Maintenance Options

  • DeploymentStrategy - RollingWithAdditionalBatch will deploy new code and platform updates by adding new servers one at a time. This option avoids downtime and is recommended for production deployments. AllAtOnce will deploy new code and platform updates to every server at the same time. This option is faster but the environment will be unavailable until the deployment is complete.
  • BeanstalkPlatformUpdateTime - If provided, this will determine the day of week and time of day that Beanstalk will automatically update the platform version. Updating the platform version is important to ensure the system is running with the latest OS patches.

VPC Network Configuration

  • VpcId - The VPC ID for where to deploy StartingBlocks resources. Must be deployed before StartingBlocks.
  • PublicSubnet1Id - The Subnet ID of a Public Subnet in one of the Availability Zones. Must be configured before StartingBlocks deployment.
  • PublicSubnet2Id - The Subnet ID of a Public Subnet in one of the Availability Zones. Must be configured before StartingBlocks deployment.
  • PrivateSubnet1Id - The Subnet ID of a Private Subnet in one of the Availability Zones. Must be configured before StartingBlocks deployment.
  • PrivateSubnet2Id - The Subnet ID of a Private Subnet in one of the Availability Zones. Must be configured before StartingBlocks deployment.