[Help needed] New Resource: aws_ssm_document_list

[PaulAtkins]

Adding aws_ssm_document_list. This based on aws_ssm_document, but allows a list of documents to be passed in.

Use Case

The use case for this is when dealing with many of these documents, instead of creating a ssm_document for every document, it's easier to get a list of documents from a folder.

Previously, I was using the powershell below to retrieve this list, and passing that to ssm_document as a list variable. This works initially, but has a few issues:

• If a document is added, renamed or deleted, it can affect the ordering of the list and the state file, causing terraform to try updating multiple documents
• If documents are added the statefile change causes move existing files down the list, causing terraform to try (and fail) to re-create an existing document
• The same re-ordering of the list can cause update issues because the document version in AWS, no longer matches the one held in state.

data "external" "doc-list" {
  program = ["powershell", "New-Object PSObject | Add-Member -PassThru NoteProperty Name ((Get-ChildItem -Path ../../docs/linux -File -Filter '*.json').Name -join ',') | ConvertTo-Json"]
}

And passing that output to a module as a variable:

variable "linux-command-doc-list" {
  type = "list"
}

resource "aws_ssm_document" "command-docs" {
  name          = "${replace(element(var.linux-command-doc-list, count.index), ".json", "")}"
  document_type = "Command"
  content       = "${file("../../docs/linux/${element(var.linux-command-doc-list, count.index)}")}"
  count         = "${length(var.linux-command-doc-list)}"
}

aws_ssm_document_list

Using aws_ssm_document_list with datasource_template_file_list, I can write this:

data "template_file_list" "list" {
  source_dir = "./docs"
}

resource "aws_ssm_document_list" "docs" {
  documents_list = ["${data.template_file_list.list.files}"]
  documents_hash = "${data.template_file_list.list.id}"
  documents_type = "Command"
}

The Create action takes all documents in the list and creates them in AWS, using partial state.

The Update action takes care of Creating / Updating / Deleting new and existing documents that get added or removed from the folder. It also takes care of avoiding making changes to documents that haven't changed (from the statefile re-ordering issue above)

The Delete action takes all documents in the list and deletes them from AWS, using partial state.

Todo / Help

• Help: How to get the list of documents from rs.Primary.Attributes["documents_list"] ?
• Help: I've duplicated a lot of code from ssm_document, because I couldn't find a way to get a *schema.ResourceData type object from d.Get("documents_list"). Is that possible a different way?
• Todo: Finish adding tests
• Todo: Add setting of document permissions
• Todo: Website / docs

[Ninir]

Hey @PaulAtkins

Before digging into the codebase, could you help us better understand the use-case please?
I read your use-case and I'm wondering whether you would have that much of documents to define?

It seems to be kind of an uncommon use-case to me, but hey, we never know 🤷‍♂️ 😄

Thanks for the answer :) 👍

[PaulAtkins]

Hey @Ninir,

Yep no worries. We have a repo of SSM Documents (Commands & Automations) shared across multiple teams and AWS accounts. Currently we have 100+ SSM documents and it's steadily growing.

A lot of these teams also use terraform, so it make sense to also manage these docs through terraform too. We've got a standardised naming, so for example:

My-SSM-Document.json would become:

resource "aws_ssm_document" "My-SSM-Document" {
    name          = "My-SSM-Document.json"
    content       = "${file("My-SSM-Document.json")}"
    document_type = "Command"
}

Maybe this PR isn't quite the right approach, but it would be awesome if we could make changes (add/update/delete) to SSM document json files in a directory and terraform pick up and apply those changes :)

A simpler / better approach might be if it's possible to create the resource "aws_ssm_document" on the fly from a template directory?

[bflad]

Hey @PaulAtkins 👋 I'm going to close out this old pull request in the repository. If there is movement again or good reason to reopen it, we can certainly revisit this.

We don't have a precedent for this type of multiple-resource within Terraform and it goes against our usual alignment of Terraform resource to API "object". I think if we are going to consider something along these lines we should probably discuss this more in an issue and come up with some design decisions that address some of your help items. 😄

The good news here is that it will be nice to see how Terraform 0.12 helps with its for_each/for support. 👍 I believe 0.12's support of that feature could really prevent the need for creating multi-resources like these.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you feel this issue should be reopened, we encourage creating a new issue linking back to this one for added context. Thanks!