Skip to content

Commit

Permalink
Added some fixes to the README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@viktor-ribchev
viktor-ribchev committed Jul 9, 2024
1 parent 63622be commit 5e19fb0
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 38 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# GraphDB AWS Terraform Module Changelog

# 1.2.0

* Added support for single node deployment
* Added new userdata script `10_start_graphdb_services.sh.tpl` for single node setup.
* Made cluster-related userdata scripts executable only when graphdb_node_count is greater than 1.
Expand All @@ -9,6 +10,7 @@
* Bumped GraphDB version to [10.7.0](https://graphdb.ontotext.com/documentation/10.7/release-notes.html#graphdb-10-7-0)

## 1.1.0

* Added support for CMK Keys
* Added support to use existing VPC and subnets to deploy the GraphDB cluster

Expand Down
92 changes: 54 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This Terraform module allows you to provision an GraphDB cluster within a Virtual Private Cloud (VPC). The module
provides a flexible way to configure the cluster and the associated VPC components. It implements the GraphDB reference
architecture. Check the official [documentation](https://graphdb.ontotext.com/documentation/10.6/aws-deployment.html)
architecture. Check the official [documentation](https://graphdb.ontotext.com/documentation/10.7/aws-deployment.html)
for more details.

## Table of contents
Expand All @@ -14,15 +14,15 @@ for more details.
- [Inputs](#inputs)
- [Usage](#usage)
- [Examples](#examples)
- [Updating configurations and GraphDB version on an active deployment](#updating-configurations-and-graphdb-version-on-an-active-deployment)
- [Updating configurations on an active deployment](#updating-configurations-on-an-active-deployment)
- [Local Development](#local-development)
- [Release History](#release-history)
- [Contributing](#contributing)
- [License](#license)

## About GraphDB

<p>
<p align="center">
<a href="https://www.ontotext.com/products/graphdb/">
<picture>
<img src="https://www.ontotext.com/wp-content/uploads/2022/09/Logo-GraphDB.svg" alt="GraphDB logo" title="GraphDB"
Expand Down Expand Up @@ -55,7 +55,7 @@ across multiple availability zones using EC2 Autoscaling Group. Key features of
## Versioning

The Terraform module follows the Semantic Versioning 2.0.0 rules and has a release lifecycle separate from the GraphDB
versions. The next table shows the version compatability between GraphDB and the Terraform module.
versions. The next table shows the version compatability between GraphDB, and the Terraform module.

| GraphDB Terraform | GraphDB |
|--------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -216,8 +216,8 @@ The following are the important variables you should configure when using this m
- `aws_region`: The region in which GraphDB will be deployed.
- `ec2_instance_type`: The instance type for the GDB cluster nodes. This should match your performance and cost
requirements.
- `graphdb_node_count`: The number of instances in the cluster. Recommended is 3, 5 or 7 in order to have consensus according to
the [Raft algorithm](https://raft.github.io/).
- `graphdb_node_count`: The number of instances in the cluster. Recommended is 3, 5 or 7 to have consensus according to
the [Raft algorithm](https://raft.github.io/). For a single node deployment set the value to 1.
- `graphdb_license_path` : The path where the license for the GraphDB resides.
- `graphdb_admin_password`: This variable allows you to set password of your choice. If nothing is specified it will be
autogenerated, you can find the autogenerated password in the SSM Parameter Store. You should know that is
Expand All @@ -239,7 +239,7 @@ module "graphdb" {
allowed_inbound_cidrs_lb = ["0.0.0.0/0"]
}
```
Initialize the module and it's required providers with:
Initialize the module and its required providers with:

`terraform init`

Expand Down Expand Up @@ -324,6 +324,17 @@ To enable the logging feature the first thing that you should do is to switch th

There are several logging features that can be enabled with the following variables:

**EBS Volume Configurations**

This Terraform module creates EBS volumes and mounts them to EC2 instances to store data.
You can modify the default settings by changing the values of the following variables:

```hcl
ebs_volume_size = 1024
ebs_volume_iops = 10000
ebs_volume_throughput = 500
```

#### S3 Access Logs

To enable the S3 Bucket access logs for the backup bucket you should switch the following values to `true`:
Expand Down Expand Up @@ -356,40 +367,44 @@ vpc_flow_logs_lifecycle_rule_status = "Enabled"

**Parameter Store encryption**

You can encrypt parameters stored in AWS Systems Manager Parameter Store using KMS CMKs. This ensures that sensitive data, such as configuration secrets, are securely encrypted at rest.
You can encrypt parameters stored in AWS Systems Manager Parameter Store using KMS CMKs. This ensures that sensitive data,
such as configuration secrets, are securely encrypted at rest.

##### Keys

To utilize CMK, ensure that **enable_graphdb_parameter_store_kms_key = true** is set. This will generate a new KMS Key.
To utilize CMK, you should set the following variable `enable_graphdb_parameter_store_kms_key` to `true`.
This will generate a new KMS Key.

If **enable_graphdb_parameter_store_kms_key = false**, encryption will be disabled.
If `enable_graphdb_parameter_store_kms_key` is set to `false`, the encryption will be disabled.

You can also supply your own key using the parameter_store_external_kms_key parameter: **parameter_store_external_kms_key**
You can also provide your own key using the `parameter_store_external_kms_key` variable.

```hcl
ebs_external_kms_key = "arn:aws:kms:us-east-1:123456789012:key/your-external-key-arn"
parameter_store_external_kms_key = "arn:aws:kms:us-east-1:123456789012:key/your-external-key-arn"
enable_graphdb_parameter_store_kms_key = true
parameter_store_external_kms_key = "arn:aws:kms:us-east-1:123456789012:key/your-external-key-arn"
```

##### Key Admin

You can designate a Key admin by setting the **graphdb_parameter_store_key_admin_arn** parameter, or you can use the current AWS account by leaving this parameter empty.
You can designate a Key admin by setting the `graphdb_parameter_store_key_admin_arn` variable,
or you can use the current AWS account by leaving this parameter empty.

```hcl
graphdb_parameter_store_key_admin_arn = "arn:aws:iam::123456789012:role/KeyAdminRole"
```

**EBS encryption**

You can secure EBS volumes using KMS CMKs to encrypt data at rest. This adds an extra layer of protection for data stored on EBS volumes attached to EC2 instances.
You can enhance the security of EBS volumes by using KMS CMKs to encrypt data at rest.
This provides an additional layer of protection for data stored on EBS volumes attached to EC2 instances.

##### Keys

To use CMK, set **create_graphdb_ebs_kms_key = true**. This will create a new KMS Key.
To enable CMK, set `create_graphdb_ebs_kms_key` to `true`. This will create a new KMS Key.

If **create_graphdb_ebs_kms_key = false** the default AWS key encryption will be used.
If `create_graphdb_ebs_kms_key` is set to `false` the default AWS key encryption will be used.

You can provide your own key by using the parameter **ebs_external_kms_key**.
You can also provide your own key using the `ebs_external_kms_key` variable.

```hcl
create_graphdb_ebs_kms_key = true
Expand All @@ -398,53 +413,55 @@ ebs_external_kms_key = "arn:aws:kms:us-east-1:123456789012:key/your-external-key

##### Key Admin

You can specify a Key admin by setting the **graphdb_ebs_key_admin_arn** parameter, or you can use the current AWS account by leaving this parameter empty.
You can designate a Key admin by setting the `graphdb_ebs_key_admin_arn` variable,
or you can use the current AWS account by leaving this parameter empty.

```hcl
graphdb_ebs_key_admin_arn = "arn:aws:iam::123456789012:role/KeyAdminRole"
```

**S3 encryption**

You can encrypt S3 bucket objects using KMS CMKs to ensure that data at rest is secure. This protects the integrity and confidentiality of data stored in S3 buckets.
You can secure S3 bucket objects by encrypting them with KMS CMKs, ensuring data at rest is protected.
This safeguards the integrity and confidentiality of data stored in S3 buckets.

##### Keys

To use CMK, set **create_s3_kms_key = true**. This will create a new KMS Key.
To use CMK, set `create_s3_kms_key` to `true`. This will create a new KMS Key.

If **create_s3_kms_key = false**, the default AWS key (**alias/aws/s3**) will be used.
If `create_s3_kms_key` is set to `false`, the default AWS key `alias/aws/s3` will be used.

You can also provide your own key by setting the **s3_external_kms_key_arn** parameter.
You can also provide your own key using the `s3_external_kms_key_arn` variable.

```hcl
create_s3_kms_key = true
s3_external_kms_key = "arn:aws:kms:us-east-1:123456789012:key/your-external-key-arn"
s3_external_kms_key_arn = "arn:aws:kms:us-east-1:123456789012:key/your-external-key-arn"
```

##### Key Admin

You can specify a Key admin by setting the **s3_kms_key_admin_arn** parameter, or you can use the current AWS account by leaving this parameter empty.
You can designate a Key admin by setting the `s3_kms_key_admin_arn` variable,
or you can use the current AWS account by leaving this parameter empty.

```hcl
s3_kms_key_admin_arn = "arn:aws:iam::123456789012:role/KeyAdminRole"
```

#### Replication

You can enable S3 Bucket replication for the S3 buckets.

To do so you should switch the following variables to true:
You can enable replication for S3 buckets by setting the following variables to true:

```hcl
logging_enable_bucket_replication = true
s3_enable_replication_rule = "Enabled"
```

#### Deploying in existing VPC
#### Deploying in an existing VPC

If you have existing VPC created in your account, you can use that VPC to deploy the GraphDB cluster.
If you have an existing VPC in your account, you can use it to deploy the GraphDB cluster.

Just specify values for the following variables:

What you need to do is to specify values for the following variables
```hcl
vpc_id = "vpc-12345678"
vpc_public_subnet_ids = ["subnet-123456","subnet-234567","subnet-345678"]
Expand All @@ -453,18 +470,18 @@ vpc_private_subnet_ids = ["subnet-456789","subnet-567891","subnet-678912"]

## Single Node Deployment

This Terraform module has the ability to deploy a single instance of GraphDB.
To deploy a single instance you just need to set `graphdb_node_count` to 1, everything else happens automatically.
This Terraform module can deploy a single instance of GraphDB.
To do this, set `graphdb_node_count` to `1`, and the rest will be handled automatically.

**Important:** While scaling from a single node deployment to a cluster (e.g., from 1 node to 3 nodes) is possible,
it is not recommended. Synchronizing the repository across all nodes can be time-consuming,
potentially causing scripts to time out.
**Important:** While it is possible to scale from a single node to a cluster deployment (e.g., from 1 node to 3 nodes),
it is not recommended. Synchronizing the repository across all nodes can be time-consuming and may cause scripts
to time out.

## Updating configurations on an active deployment

### Updating Configurations

When faced with scenarios such as an expired license, or the need to modify the graphdb.properties file or other
When faced with scenarios such as an expired license, or the need to modify the `graphdb.properties` file or other
GraphDB-related configurations, you can apply changes via `terraform apply` and then you can either:

- Manually terminate instances one by one, beginning with the follower nodes and concluding with the leader node
Expand Down Expand Up @@ -493,7 +510,6 @@ This delay allows GraphDB time to sync with other nodes.
You can adjust this delay by changing the `asg_instance_refresh_checkpoint_delay` value.
If there are many writes to the cluster, consider increasing this delay.


Note that any changes to GraphDB configurations will be applied during the instance refresh process,
except for the `graphdb_admin_password`.
Support for updating the admin password will be introduced in a future release.
Expand Down

0 comments on commit 5e19fb0

Please sign in to comment.