Skip to content

Commit

Permalink
Merge pull request #26 from Ontotext-AD/TES-367-documentation
Browse files Browse the repository at this point in the history 
TES-367: Document the Terraform module
  • Loading branch information
@mihailradkov
mihailradkov authored Dec 6, 2023
2 parents 5d60bb7 + 42bcbae commit 691adf2
Show file tree
Hide file tree
Showing 5 changed files with 294 additions and 16 deletions.
48 changes: 48 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Contributing Guidelines

Here are a few guidelines to help you get started.

## Getting Started

1. Fork this repository.
2. Clone your forked repository to your local machine.
3. Create a new branch for your changes: `git checkout -b feature/my-new-feature`.
4. Make your changes and test them thoroughly.
5. Commit your changes: `git commit -m "Add some feature"`.
6. Push your changes to your fork: `git push origin feature/my-new-feature`.
7. Create a pull request from your branch to the main repository's `main` branch.

## Code Style

Make sure your code follows our and Terraform coding styles.

## Tests

If applicable, add or update tests to ensure your changes work as intended.

## Documentation

If your changes introduce new features, update the documentation to reflect those changes.

## Commit Message Guidelines

Please use meaningful commit messages. Follow the format:

```
[Type] Short description
Longer description of the changes, especially whys.
```

Types: `[Feature]`, `[Fix]`, `[Docs]`, `[Refactor]`, `[Chore]`, `[Style]`

## Pull Request Checklist

- [ ] I have tested these changes thoroughly.
- [ ] My code follows the project's coding style.
- [ ] I have added appropriate comments to my code, especially in complex areas.
- [ ] All new and existing tests passed locally.

## Feedback

Feedback and suggestions are welcome! Feel free to open an issue if you have any questions or ideas.
200 changes: 200 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,205 @@
# GraphDB Azure Terraform Module

[![CI](https://github.com/Ontotext-AD/terraform-azure-graphdb/actions/workflows/ci.yml/badge.svg)](https://github.com/Ontotext-AD/terraform-azure-graphdb/actions/workflows/ci.yml)

This repository contains a set of [Terraform](https://www.terraform.io/) modules for
deploying [Ontotext GraphDB](https://www.ontotext.com/products/graphdb/)
HA cluster on [Microsoft Azure](https://azure.microsoft.com/).

## Table of Contents

- [About GraphDB](#about-graphdb)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Configurations](#configurations)
- [Usage](#usage)
- [Examples](#examples)
- [Local Development](#local-development)
- [Release History](#release-history)
- [Contributing](#contributing)
- [License](#license)

## About GraphDB

<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" height="75">
</picture>
</a>
</p>

Ontotext GraphDB is a highly efficient, scalable and robust graph database with RDF and SPARQL support. With excellent enterprise features,
integration with external search applications, compatibility with industry standards, and both community and commercial support, GraphDB is the
preferred database choice of both small independent developers and big enterprises.

<!---
TODO link to azure marketplace?
-->

## Features

The module provides the building blocks of configuring, deploying and provisioning a highly available cluster of GraphDB across multiple availability
zones using a VM scale set. Key features of the module include:

- Azure VM scale set across multiple Availability Zones
- Azure Application Gateway for load balancing and TLS termination
- Azure NAT gateway for outbound connections
- Automated backups in Azure Blob Storage
- Azure Private DNS for internal GraphDB cluster communication
- Azure Key Vault for storing sensitive configurations
- Optional Azure Bastion deployment
- User assigned identities for RBAC authorization with the least privilege principle
- and more

<!---
TODO list the key features of the module as well as the purpose of the modules + maybe some diagram?
See https://github.com/hashicorp/terraform-aws-consul
-->

## Prerequisites

- Subscription in Microsoft Azure
- Azure CLI https://learn.microsoft.com/en-us/cli/azure/install-azure-cli
- Terraform CLI v1.5+ https://developer.hashicorp.com/terraform/install?product_intent=terraform
- License for GraphDB Enterprise Edition

You then need to authenticate in your subscription with Azure CLI,
see [Authenticating using the Azure CLI](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/azure_cli) for more details.

## Configurations

The module support different variables that customize the deployment. Inside [variables.tf](variables.tf) you can see all the supported
options.

<!-- BEGIN_TF_DOCS -->

| Name | Description | Type | Default | Required |
|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|----------------|-------------------------|:--------:|
| resource\_name\_prefix | Resource name prefix used for tagging and naming Azure resources | `string` | n/a | yes |
| location | Azure geographical location where resources will be deployed | `string` | n/a | yes |
| zones | Availability zones to use for resource deployment and HA | `list(number)` | ```[ 1, 2, 3 ]``` | no |
| tags | Common resource tags. | `map(string)` | `{}` | no |
| lock\_resources | Enables a delete lock on the resource group to prevent accidental deletions. | `bool` | `true` | no |
| virtual\_network\_address\_space | Virtual network address space CIDRs. | `list(string)` | ```[ "10.0.0.0/16" ]``` | no |
| app\_gateway\_subnet\_address\_prefix | Subnet address prefix CIDRs where the application gateway will reside. | `list(string)` | ```[ "10.0.1.0/24" ]``` | no |
| graphdb\_subnet\_address\_prefix | Subnet address prefix CIDRs where GraphDB VMs will reside. | `list(string)` | ```[ "10.0.2.0/24" ]``` | no |
| management\_cidr\_blocks | CIDR blocks allowed to perform management operations such as connecting to Bastion or Key Vault. | `list(string)` | n/a | yes |
| tls\_certificate\_path | Path to a TLS certificate that will be imported in Azure Key Vault and used in the Application Gateway TLS listener for GraphDB. | `string` | n/a | yes |
| tls\_certificate\_password | TLS certificate password for password protected certificates. | `string` | `null` | no |
| key\_vault\_enable\_purge\_protection | Prevents purging the key vault and its contents by soft deleting it. It will be deleted once the soft delete retention has passed. | `bool` | `false` | no |
| key\_vault\_retention\_days | Retention period in days during which soft deleted secrets are kept | `number` | `30` | no |
| graphdb\_version | GraphDB version to deploy | `string` | `"10.4.1"` | no |
| graphdb\_image\_id | Image ID to use for running GraphDB VM instances. If left unspecified, Terraform will use the image from our public Compute Gallery. | `string` | `null` | no |
| graphdb\_license\_path | Local path to a file, containing a GraphDB Enterprise license. | `string` | n/a | yes |
| graphdb\_cluster\_token | Secret token used to secure the internal GraphDB cluster communication. Will generate one if left undeclared. | `string` | `null` | no |
| graphdb\_password | Secret token used to access GraphDB cluster. | `string` | `null` | no |
| graphdb\_properties\_path | Path to a local file containing GraphDB properties (graphdb.properties) that would be appended to the default in the VM. | `string` | `null` | no |
| graphdb\_java\_options | GraphDB options to pass to GraphDB with GRAPHDB\_JAVA\_OPTS environment variable. | `string` | `null` | no |
| node\_count | Number of GraphDB nodes to deploy in ASG | `number` | `3` | no |
| instance\_type | Azure instance type | `string` | n/a | yes |
| ssh\_key | Public key for accessing the GraphDB instances | `string` | `null` | no |
| custom\_graphdb\_vm\_user\_data | Custom user data script used during the cloud init phase in the GraphDB VMs. Should be in base64 encoding. | `string` | `null` | no |
| storage\_account\_tier | Specify the performance and redundancy characteristics of the Azure Storage Account that you are creating | `string` | `"Standard"` | no |
| storage\_account\_replication\_type | Specify the data redundancy strategy for your Azure Storage Account | `string` | `"ZRS"` | no |
| backup\_schedule | Cron expression for the backup job. | `string` | `"0 0 * * *"` | no |
| disk\_size\_gb | Size of the managed data disk which will be created | `number` | `500` | no |
| disk\_iops\_read\_write | Data disk IOPS | `number` | `7500` | no |
| disk\_mbps\_read\_write | Data disk throughput | `number` | `250` | no |
| deploy\_bastion | Deploy bastion module | `bool` | `false` | no |
| bastion\_subnet\_address\_prefix | Bastion subnet address prefix | `list(string)` | ```[ "10.0.3.0/27" ]``` | no |

<!-- END_TF_DOCS -->

## Usage

To use the GraphDB module, create a new Terraform project or add to an existing one the following module block:

```hcl
module "graphdb" {
source = "Ontotext-AD/graphdb/azure"
version = "1.0.0"
resource_name_prefix = "graphdb"
location = "East US"
zones = [1, 2, 3]
tags = {
Environment : "dev"
}
instance_type = "Standard_E8as_v5"
graphdb_license_path = "path-to-graphdb-license"
ssh_key = "your-public-key"
management_cidr_blocks = ["your-ip-address"]
tls_certificate_path = "path-to-your-tls-certificate"
}
```

Initialize the module and its required providers with:

```bash
terraform init
```

Before deploying, make sure to inspect the plan output with:

```bash
terraform plan
```

After a careful review of the output plan, deploy with:

```bash
terraform apply
```

Once deployed, you should be able to access the environment at the generated FQDN that has been outputted at the end.

## Examples

**Bastion**

To enable the deployment of Azure Bastion, you simply need to enable the following flag:

```hcl
deploy_bastion = true
```

**GraphDB admin password**

Instead of generating a random administrator password, you can provide one with:

```hcl
graphdb_password = "s3cr37P@$w0rD"
```

<!---
TODO Add more examples
-->

<!---
## Next Steps
TODO Configure security, provisioning etc. links for loading data? backend for state
-->

## Local Development

Instead of using the module as dependency, you can create a local variables file named `terraform.tfvars` and provide configuration overrides there.
Then simply follow the same steps as in the [Usage](#usage) section.

## Release History

All notable changes between version are tracked and documented at [CHANGELOG.md](CHANGELOG.md).

## Contributing

Check out the contributors guide [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This code is released under the Apache 2.0 License. See [LICENSE](LICENSE) for more details.

<!---
TODO Do we need a copyright statement? Even if the code is released under Apache?
-->
16 changes: 0 additions & 16 deletions main.tf
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,3 @@
provider "azurerm" {
features {
managed_disk {
expand_without_downtime = true
}
resource_group {
prevent_deletion_if_contains_resources = true
}
key_vault {
purge_soft_delete_on_destroy = true
}
}
# Required when shared_access_key_enabled is false
storage_use_azuread = true
}

locals {
tags = merge({
# Used to easily track all resource managed by Terraform
Expand Down
15 changes: 15 additions & 0 deletions provider.tf
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
provider "azurerm" {
features {
managed_disk {
expand_without_downtime = true
}
resource_group {
prevent_deletion_if_contains_resources = true
}
key_vault {
purge_soft_delete_on_destroy = true
}
}
# Required when shared_access_key_enabled is false
storage_use_azuread = true
}
31 changes: 31 additions & 0 deletions terraform-docs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
formatter: markdown table

sections:
show:
- inputs

output:
file: README.md
mode: inject
template: |-
<!-- BEGIN_TF_DOCS -->
{{ .Content }}
<!-- END_TF_DOCS -->
sort:
enabled: false

settings:
anchor: false
color: true
default: true
description: false
escape: true
hide-empty: false
html: false
indent: 2
lockfile: true
read-comments: true
required: true
sensitive: true
type: true

0 comments on commit 691adf2

Please sign in to comment.