Docs

wttech · Nov 17, 2023 · 02a492c · 02a492c
1 parent f5b2c90
commit 02a492c
Show file tree

Hide file tree

Showing 17 changed files with 175 additions and 147 deletions.
diff --git a/GNUmakefile b/GNUmakefile
@@ -1,7 +1,8 @@
-default: testacc
+default: all
 
 # Run acceptance tests
 .PHONY: testacc
+
 testacc:
 	TF_ACC=1 go test ./... -v $(TESTARGS) -timeout 120m
 
@@ -10,3 +11,5 @@ lint:
 
 generate:
 	go generate ./...
+
+all: lint generate testacc
diff --git a/README.md b/README.md
@@ -9,104 +9,6 @@ Allows to manage and provision Adobe Experience Manager (AEM) instances declarat
 
 Built on top of [AEM Compose](https://github.com/wttech/aemc).
 
-## Examples
-
-### Bare metal example
-
-Assumes that AEM files will be copied from local `lib` directory.
-
-```hcl
-resource "aem_instance" "single" {
-  files = {
-    "lib" = "${local.aem_single_compose_dir}/aem/home/lib"
-  }
-
-  system {
-    data_dir = local.aem_single_compose_dir
-  }
-  
-  client {
-    type = "ssh"
-    settings = {
-      host   = "x.x.x.x" // IP address of the machine
-      user   = "some-user-with-sudo"
-    }
-    credentials = {
-      private_key = file(local.ssh_private_key)
-    }
-  }
-
-  compose {}
-}
-
-locals {
-  aem_single_data_dir    = "/data"
-  aem_single_compose_dir = "${local.aem_single_data_dir}/aemc"
-}
-```
-
-### AWS example
-
-Assumes that AEM files are uploaded to S3 bucket `aemc` and are available under `s3://aemc/instance/classic/`.
-
-```hcl
-resource "aem_instance" "single" {
-  depends_on = [aws_instance.aem_single, aws_volume_attachment.aem_single_data]
-
-  client {
-    type = "ssh"
-    settings = {
-      host   = aws_instance.aem_single.public_ip
-      user   = local.ssh_user
-    }
-    credentials = {
-      private_key = file(local.ssh_private_key)
-    }
-  }
-
-  system {
-    data_dir = local.aem_single_compose_dir
-    bootstrap = {
-      inline = [
-        // mounting AWS EBS volume into data directory
-        "sudo mkfs -t ext4 ${local.aem_single_data_device}",
-        "sudo mkdir -p ${local.aem_single_data_dir}",
-        "sudo mount ${local.aem_single_data_device} ${local.aem_single_data_dir}",
-        "sudo chown -R ${local.ssh_user} ${local.aem_single_data_dir}",
-        "echo '${local.aem_single_data_device} ${local.aem_single_data_dir} ext4 defaults 0 0' | sudo tee -a /etc/fstab",
-        // installing AWS CLI
-        "sudo yum install -y unzip",
-        "curl 'https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip' -o 'awscliv2.zip'",
-        "unzip -q awscliv2.zip",
-        "sudo ./aws/install --update",
-      ]
-    }
-  }
-
-  compose {
-    create = {
-      inline = [
-        "mkdir -p '${local.aem_single_compose_dir}/aem/home/lib'",
-        "aws s3 cp --recursive --no-progress 's3://aemc/instance/classic/' '${local.aem_single_compose_dir}/aem/home/lib'",
-        "sh aemw instance init",
-        "sh aemw instance create",
-      ]
-    }
-  }
-}
-
-locals {
-  // https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html#device-name-limits
-  aem_single_data_device = "/dev/nvme1n1"
-  aem_single_data_dir    = "/data"
-  aem_single_compose_dir = "${local.aem_single_data_dir}/aemc"
-}
-
-output "aem_instances" {
-  value = aem_instance.single.instances
-}
-```
-
 ## Requirements
 
 - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0

diff --git a/docs/index.md b/docs/index.md
@@ -1,20 +1,33 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "aem Provider"
+page_title: "AEM Provider"
 subcategory: ""
-description: |-
-  
 ---
 
-# aem Provider
+[![AEM Compose Logo](https://github.com/wttech/aemc/raw/main/docs/logo-with-text.png)](https://github.com/wttech/aemc)
+[![WTT Logo](https://github.com/wttech/aemc/raw/main/docs/wtt-logo.png)](https://www.wundermanthompson.com/service/technology)
 
+# AEM Provider
 
+This provider allows developers and development teams to easily set up [Adobe Experience Manager (AEM)](https://business.adobe.com/products/experience-manager/adobe-experience-manager.html) instances on virtual machines in the cloud or bare metal machines. 
+It's based on the [AEM Compose](https://github.com/wttech/aemc) tool and aims to simplify the process of creating AEM environments without requiring deep DevOps knowledge. 
+Only basic AWS, Azure, or any other cloud knowledge about VMs is required.
 
+## Purpose
+
+The main purpose of this provider is to enable users to:
+
+- Set up as many AEM environments as needed with minimal effort
+- Eliminate the need for deep DevOps knowledge
+- Allow for seamless integration with popular cloud platforms such as AWS and Azure
+- Provide a simple and efficient way to manage AEM instances
+
+## Features
+
+- Easy configuration and management of AEM instances
+- Support for multiple cloud platforms and bare metal machines
+- Seamless integration with Terraform for infrastructure provisioning
+- Based on the powerful [AEM Compose](https://github.com/wttech/aemc) tool
 
 
-<!-- schema generated by tfplugindocs -->
-## Schema
 
-### Optional
 
-- `endpoint` (String) Example provider attribute
diff --git a/docs/resources/instance.md b/docs/resources/instance.md
@@ -1,14 +1,26 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "aem_instance Resource - terraform-provider-aem"
+page_title: "AEM Provider - Resource 'aem_instance'"
 subcategory: ""
-description: |-
-  AEM Instance resource
 ---
 
-# aem_instance (Resource)
+[![AEM Compose Logo](https://github.com/wttech/aemc/raw/main/docs/logo-with-text.png)](https://github.com/wttech/aemc)
+[![WTT Logo](https://github.com/wttech/aemc/raw/main/docs/wtt-logo.png)](https://www.wundermanthompson.com/service/technology)
 
-AEM Instance resource
+# AEM Provider - Resource 'aem_instance'
+
+The instance resource allows you to create and manage AEM instances.
+
+With this resource, you can set up one or many AEM instances on a single machine. 
+
+If you need to set up multiple AEM instances on multiple machines, you can use this resource multiple times. However, remember to use different client settings and adapt the compose configuration accordingly. This is because the default configuration assumes that both AEM author and publish are set up on the same machine.
+
+## Example usages
+
+Consider reviewing the following examples to find the one that best suits your needs:
+
+1. [AWS EC2 instance with public IP](https://github.com/wttech/terraform-provider-aem/tree/main/examples/aws_ssh)
+2. [AWS EC2 instance with private IP](https://github.com/wttech/terraform-provider-aem/tree/main/examples/aws_ssm)
+3. [Bare metal machine](https://github.com/wttech/terraform-provider-aem/tree/main/examples/bare_metal_ssh)
 
 
 
@@ -17,22 +29,22 @@ AEM Instance resource
 
 ### Optional
 
-- `client` (Block, Optional) (see [below for nested schema](#nestedblock--client))
-- `compose` (Block, Optional) AEM Compose CLI configuration (see [below for nested schema](#nestedblock--compose))
-- `files` (Map of String) Files or directories to be copied into the machine
-- `system` (Block, Optional) (see [below for nested schema](#nestedblock--system))
+- `client` (Block, Optional) Connection settings used to access the machine on which the AEM instance will be running. (see [below for nested schema](#nestedblock--client))
+- `compose` (Block, Optional) AEM Compose CLI configuration. See [documentation](https://github.com/wttech/aemc#configuration). (see [below for nested schema](#nestedblock--compose))
+- `files` (Map of String) Files or directories to be copied into the machine.
+- `system` (Block, Optional) Operating system configuration for the machine on which AEM instance will be running. (see [below for nested schema](#nestedblock--system))
 
 ### Read-Only
 
-- `instances` (Attributes List) (see [below for nested schema](#nestedatt--instances))
+- `instances` (Attributes List) Current state of the configured AEM instances. (see [below for nested schema](#nestedatt--instances))
 
 <a id="nestedblock--client"></a>
 ### Nested Schema for `client`
 
 Required:
 
 - `settings` (Map of String) Settings for the connection type
-- `type` (String) Type of connection to use to connect to the machine on which AEM instance will be running
+- `type` (String) Type of connection to use to connect to the machine on which AEM instance will be running.
 
 Optional:
 
@@ -45,32 +57,32 @@ Optional:
 Optional:
 
 - `config` (String) Contents o f the AEM Compose YML configuration file.
-- `create` (Attributes) Creates the instance or restores from backup, typically customized to provide AEM library files (quickstart.jar, license.properties, service packs) from alternative sources (e.g., AWS S3, Azure Blob Storage). Instance recreation is forced if changed. (see [below for nested schema](#nestedatt--compose--create))
-- `delete` (Attributes) Deletes the instance. (see [below for nested schema](#nestedatt--compose--delete))
+- `configure` (Attributes) Script(s) for configuring a launched instance. Must be idempotent as it is executed always when changed. Typically used for installing AEM service packs, setting up replication agents, etc. (see [below for nested schema](#nestedatt--compose--configure))
+- `create` (Attributes) Script(s) for creating an instance or restoring it from a backup. Typically customized to provide AEM library files (quickstart.jar, license.properties, service packs) from alternative sources (e.g., AWS S3, Azure Blob Storage). Instance recreation is forced if changed. (see [below for nested schema](#nestedatt--compose--create))
+- `delete` (Attributes) Script(s) for deleting a stopped instance. (see [below for nested schema](#nestedatt--compose--delete))
 - `download` (Boolean) Toggle automatic AEM Compose CLI wrapper download. If set to false, assume the wrapper is present in the data directory.
-- `launch` (Attributes) Configures launched instance. Must be idempotent as it is executed always when changed. Typically used for installing AEM service packs, setting up replication agents, etc. (see [below for nested schema](#nestedatt--compose--launch))
-- `version` (String) Version of AEM Compose tool to use on remote AEM machine.
+- `version` (String) Version of AEM Compose tool to use on remote machine.
 
-<a id="nestedatt--compose--create"></a>
-### Nested Schema for `compose.create`
+<a id="nestedatt--compose--configure"></a>
+### Nested Schema for `compose.configure`
 
 Optional:
 
 - `inline` (List of String) Inline shell commands to be executed
 - `script` (String) Multiline shell script to be executed
 
 
-<a id="nestedatt--compose--delete"></a>
-### Nested Schema for `compose.delete`
+<a id="nestedatt--compose--create"></a>
+### Nested Schema for `compose.create`
 
 Optional:
 
 - `inline` (List of String) Inline shell commands to be executed
 - `script` (String) Multiline shell script to be executed
 
 
-<a id="nestedatt--compose--launch"></a>
-### Nested Schema for `compose.launch`
+<a id="nestedatt--compose--delete"></a>
+### Nested Schema for `compose.delete`
 
 Optional:
 
@@ -84,12 +96,12 @@ Optional:
 
 Optional:
 
-- `bootstrap` (Attributes) Script executed once upon instance connection, often for mounting on VM data volumes from attached disks (e.g., AWS EBS, Azure Disk Storage). This script runs only once, even during instance recreation, as changes are typically persistent and system-wide. If re-execution is needed, it is recommended to set up a new VM. (see [below for nested schema](#nestedatt--system--bootstrap))
-- `data_dir` (String) Remote root path in which AEM Compose files and unpacked instances will be stored
-- `env` (Map of String) Environment variables for AEM instances
-- `service_config` (String) Contents of the AEM 'systemd' service definition file
+- `bootstrap` (Attributes) Script executed once upon instance connection, often for mounting on VM data volumes from attached disks (e.g., AWS EBS, Azure Disk Storage). This script runs only once, even during instance recreation, as changes are typically persistent and system-wide. If re-execution is needed, it is recommended to set up a new machine. (see [below for nested schema](#nestedatt--system--bootstrap))
+- `data_dir` (String) Remote root path in which AEM Compose files and unpacked AEM instances will be stored.
+- `env` (Map of String) Environment variables for AEM instances.
+- `service_config` (String) Contents of the AEM system service definition file (systemd).
 - `user` (String) System user under which AEM instance will be running. By default, the same as the user used to connect to the machine.
-- `work_dir` (String) Remote root path in which AEM Compose TF provider temporary files will be stored
+- `work_dir` (String) Remote root path where provider-related files will be stored.
 
 <a id="nestedatt--system--bootstrap"></a>
 ### Nested Schema for `system.bootstrap`
@@ -106,9 +118,9 @@ Optional:
 
 Read-Only:
 
-- `aem_version` (String)
-- `attributes` (List of String)
-- `dir` (String)
-- `id` (String)
-- `run_modes` (List of String)
-- `url` (String)
+- `aem_version` (String) Version of the AEM instance. Reflects service pack installations.
+- `attributes` (List of String) A brief description of the state details for a specific AEM instance. Possible states include 'created', 'uncreated', 'running', 'unreachable', 'up-to-date', and 'out-of-date'.
+- `dir` (String) Remote path in which AEM instance is stored.
+- `id` (String) Unique identifier of AEM instance defined in the configuration.
+- `run_modes` (List of String) A list of run modes for a specific AEM instance.
+- `url` (String) The machine-internal HTTP URL address used for communication with the AEM instance.
diff --git a/examples/ssh/aem.tf → examples/aws_ssh/aem.tf b/examples/ssh/aem.tf → examples/aws_ssh/aem.tf
diff --git a/examples/ssh/aws.tf → examples/aws_ssh/aws.tf b/examples/ssh/aws.tf → examples/aws_ssh/aws.tf
diff --git a/examples/ssh/main.tf → examples/aws_ssh/main.tf b/examples/ssh/main.tf → examples/aws_ssh/main.tf
@@ -1,7 +1,8 @@
 terraform {
   required_providers {
     aem = {
-      source = "registry.terraform.io/wttech/aem"
+      source  = "registry.terraform.io/wttech/aem"
+      version = "< 2.0.0"
     }
     aws = {
       source  = "hashicorp/aws"

diff --git a/examples/aws_ssm/main.tf b/examples/aws_ssm/main.tf
@@ -1,7 +1,8 @@
 terraform {
   required_providers {
     aem = {
-      source = "registry.terraform.io/wttech/aem"
+      source  = "registry.terraform.io/wttech/aem"
+      version = "< 2.0.0"
     }
     aws = {
       source  = "hashicorp/aws"

diff --git a/examples/bare_metal_ssh/aem.tf b/examples/bare_metal_ssh/aem.tf
@@ -0,0 +1,25 @@
+resource "aem_instance" "single" {
+  client {
+    type = "ssh"
+    settings = {
+      host   = "x.x.x.x"
+      port   = 22
+      user   = "root"
+      secure = false
+    }
+    credentials = {
+      private_key = file("private_key.pem")
+    }
+  }
+
+  files = {
+    "lib" = "/data/aemc/aem/home/lib"
+  }
+
+  system {}
+  compose {}
+}
+
+output "aem_instances" {
+  value = aem_instance.single.instances
+}
diff --git a/examples/bare_metal_ssh/main.tf b/examples/bare_metal_ssh/main.tf
@@ -0,0 +1,10 @@
+terraform {
+  required_providers {
+    aem = {
+      source  = "registry.terraform.io/wttech/aem"
+      version = "< 2.0.0"
+    }
+  }
+}
+
+provider "aem" {}
diff --git a/internal/provider/description.md b/internal/provider/description.md
@@ -1,5 +1,3 @@
-# Adobe Experience Manager (AEM) Terraform Provider
-
 This provider allows developers and development teams to easily set up [Adobe Experience Manager (AEM)](https://business.adobe.com/products/experience-manager/adobe-experience-manager.html) instances on virtual machines in the cloud or bare metal machines. 
 It's based on the [AEM Compose](https://github.com/wttech/aemc) tool and aims to simplify the process of creating AEM environments without requiring deep DevOps knowledge. 
 Only basic AWS, Azure, or any other cloud knowledge about VMs is required.

diff --git a/internal/provider/instance/consts.go b/internal/provider/instance/consts.go
@@ -2,6 +2,9 @@ package instance
 
 import _ "embed"
 
+//go:embed description.md
+var DescriptionMD string
+
 //go:embed aem.yml
 var ConfigYML string
 

diff --git a/internal/provider/instance/description.md b/internal/provider/instance/description.md
@@ -0,0 +1,13 @@
+The instance resource allows you to create and manage AEM instances.
+
+With this resource, you can set up one or many AEM instances on a single machine. 
+
+If you need to set up multiple AEM instances on multiple machines, you can use this resource multiple times. However, remember to use different client settings and adapt the compose configuration accordingly. This is because the default configuration assumes that both AEM author and publish are set up on the same machine.
+
+## Example usages
+
+Consider reviewing the following examples to find the one that best suits your needs:
+
+1. [AWS EC2 instance with public IP](https://github.com/wttech/terraform-provider-aem/tree/main/examples/aws_ssh)
+2. [AWS EC2 instance with private IP](https://github.com/wttech/terraform-provider-aem/tree/main/examples/aws_ssm)
+3. [Bare metal machine](https://github.com/wttech/terraform-provider-aem/tree/main/examples/bare_metal_ssh)
diff --git a/internal/provider/instance_model.go b/internal/provider/instance_model.go
@@ -102,7 +102,7 @@ func (o InstanceStatusItemModel) attrTypes() map[string]attr.Type {
 
 func (r *InstanceResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "AEM Instance resource",
+		MarkdownDescription: instance.DescriptionMD,
 		Blocks: map[string]schema.Block{
 			"client": schema.SingleNestedBlock{
 				MarkdownDescription: "Connection settings used to access the machine on which the AEM instance will be running.",