update doc, add example

terraform-modules · Jul 3, 2024 · 0298341 · 0298341
1 parent 91baa98
commit 0298341
Show file tree

Hide file tree

Showing 5 changed files with 289 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -228,8 +228,108 @@ org-project/openjdk-8	817869416306.dkr.ecr.us-gov-east-1.amazonaws.com/org-proje
 This variable is required because this module calls a script, and it uses `aws` CLI commands.  As such, it needs to set the `AWS_PROFILE` environment
 variable to call the script properly.
 
+## enable\_lifecycle\_policy
+
+This enables or disables setting of ECR lifecycle policies for the associated respositories.  It is
+false by default, but this may change at a later date.
+
+```hcl
+  enable_lifecycle_policy = true
+```
+
+To effectively enable polices, one of the other `lifecycle_policy_*` variables must be set:
+
+* lifecycle\_policy\_all
+* lifecycle\_policy\_prefix
+* lifecycle\_policy\_pattern
+* lifecycle\_policy\_explicit
+
+## lifecycle\_policy\_all
+
+If lifecyle policies are enabled (`enable_lifecycle_policy=true`), this will use a default lifecycle policy (any), keeping only 5 copies of an image within all repositories created
+with this module (`application_list`), excluding those in from `image_config`.
+
+This will exclude repositories defined in all of the other `lifecycle_policy_*` variables, which will have their own policy applied.
+
+* lifecycle\_policy\_prefix
+* lifecycle\_policy\_pattern
+* lifecycle\_policy\_explicit
+
+## lifecycle\_policy\_prefix
+
+This is an object with several keys:
+
+* repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the prefixes defined in `values`
+* values: a list of prefixes
+* count: the number of images to keep (default is 5)
+
+```hcl
+  lifecycle_policy_prefix = {
+    repos = [
+      "app1",
+      "app2",
+    ]
+    values = ["dev_", "uat_", "sit_"]
+    count = 5
+  }
+```
+
+This will set a policy on repos `app1` and `app2`, with 4 rules , one of which is untagged images (keep 5), and the others are the prefix `dev_`, `uat_`, and `sit_` (keep 5 of each prefix).
+Note this is not the same as a prefix list (see the [docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html)) in a single rule,
+which would have to match ALL the prefixes. To do more complicated policies, use the [explicit](#lifecycle-policy-explicit) variable.
+
+## lifecycle\_policy\_pattern
+
+This is very much like the prefix policy above, but for a pattern.  It is an object with several keys:
+
+* repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the patterns defined in `values`
+* values: a list of prefixes
+* count: the number of images to keep (default is 5)
+
+```hcl
+  lifecycle_policy_pattern = {
+    repos = [
+      "subapp/new1app1",
+      "subapp/new1app2",
+    ]
+    values = ["*.rc.*"]
+  }
+```
+
+This would create a policy on
+This will set a policy on repos `sub app/newapp1` and `subapp/newapp2`, with 2 rules , one of which is untagged images (keep 5), and the other looking for a pattern of `*.rc.*` (keeping 5).
+Note this is not the same as a pattern list (see the [docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html)) in a single rule,
+which would have to match ALL the patterns. To do more complicated policies, use the [explicit](#lifecycle-policy-explicit) variable.
+
+## lifecycle\_policy\_explicit
+
+This one allows more control, but you have to write your own policy.  See the [Terraform resource doc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ecr_lifecycle_policy_document)
+for information on how.  Specify the list of repos, and then the explicit policy to apply. Note this does not allow for more than one set of custom policies.  It is not expected that this will
+get much use.
+
+This is an object with several keys:
+
+* repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the policy defined in `policy`
+* policy: a formatted ECR lifecycle policy JSON string
+
+```
+  lifecycle_policy_explicit = {
+    repos = [
+      "subapp/new1app3",
+    ]
+    policy = data.aws_ecr_lifecycle_policy_document.pushed.json
+  }
+}
+
+This will apply a custom policy `data.aws_ecr_lifecycle_policy_document.pushed.json` to the repo `subapp/new1app3`.
+
+# Examples
+* [Simple](examples/simple)
+* [Lifecycle Policy](examples/lifecycle-policy)
+
 # Caveats
-Currently, a destroy of the images (null\_resources) does **NOT** remove the repository. That is a work in progress.
+Currently, a destroy of the images (null_resources) does **NOT** remove the repository. That is a work in progress.
+```
 
 ## Requirements
 
@@ -287,7 +387,7 @@ No modules.
 | <a name="input_image_config"></a> [image\_config](#input\_image\_config) | List of image configuration objects to copy from SOURCE to DESTINATION | <pre>list(object({<br>    name            = string,<br>    tag             = string,<br>    dest_path       = string,<br>    source_registry = string,<br>    source_image    = string,<br>    source_tag      = string,<br>    enabled         = bool,<br>  }))</pre> | `[]` | no |
 | <a name="input_lifecycle_policy_all"></a> [lifecycle\_policy\_all](#input\_lifecycle\_policy\_all) | Flag to enable the same default policy (any, count of 5) if true | `bool` | `false` | no |
 | <a name="input_lifecycle_policy_default"></a> [lifecycle\_policy\_default](#input\_lifecycle\_policy\_default) | Object with settings for selecting repositories to apply a policy for 'any'.  Select repo list and number of images to keep (default: 5). | <pre>object({<br>    repos = list(string)<br>    count = optional(number, 5)<br>  })</pre> | <pre>{<br>  "count": 5,<br>  "repos": []<br>}</pre> | no |
-| <a name="input_lifecycle_policy_explicit"></a> [lifecycle\_policy\_explicit](#input\_lifecycle\_policy\_explicit) | Object with settings for selecting repositories to apply a policy for an explicit policy.  Select repo list and number of images to keep (default: 5), and a policy defined using `data.aws_ecr_lifecycle_policy_document.{name}.json'` | <pre>object({<br>    count  = optional(number, 5)<br>    repos  = list(string)<br>    policy = string<br>  })</pre> | <pre>{<br>  "count": 5,<br>  "policy": null,<br>  "repos": []<br>}</pre> | no |
+| <a name="input_lifecycle_policy_explicit"></a> [lifecycle\_policy\_explicit](#input\_lifecycle\_policy\_explicit) | Object with settings for selecting repositories to apply a policy for an explicit policy.  Select repo list and number of images to keep (default: 5), and a policy defined using `data.aws_ecr_lifecycle_policy_document.{name}.json'` | <pre>object({<br>    repos  = list(string)<br>    policy = string<br>  })</pre> | <pre>{<br>  "policy": null,<br>  "repos": []<br>}</pre> | no |
 | <a name="input_lifecycle_policy_pattern"></a> [lifecycle\_policy\_pattern](#input\_lifecycle\_policy\_pattern) | Object with settings for selecting repositories to apply a policy for 'pattern'.  Select repo list and number of images to keep (default: 5), and a list of patterns (will create one rule per pattern). | <pre>object({<br>    count  = optional(number, 5)<br>    repos  = list(string)<br>    values = list(string)<br>  })</pre> | <pre>{<br>  "count": 5,<br>  "repos": [],<br>  "values": []<br>}</pre> | no |
 | <a name="input_lifecycle_policy_prefix"></a> [lifecycle\_policy\_prefix](#input\_lifecycle\_policy\_prefix) | Object with settings for selecting repositories to apply a policy for 'prefix'.  Select repo list and number of images to keep (default: 5), and a list of prefixes (will create one rule per prefix). | <pre>object({<br>    count  = optional(number, 5)<br>    repos  = list(string)<br>    values = list(string)<br>  })</pre> | <pre>{<br>  "count": 5,<br>  "repos": [],<br>  "values": []<br>}</pre> | no |
 | <a name="input_override_prefixes"></a> [override\_prefixes](#input\_override\_prefixes) | Override built-in prefixes by component. This should be used primarily for common infrastructure things | `map(string)` | `{}` | no |

diff --git a/examples/lifecycle-policy/images.tf b/examples/lifecycle-policy/images.tf
@@ -0,0 +1,64 @@
+module "images" {
+  source = "git@github.e.it.census.gov:terraform-modules/aws-ecr-copy-images.git"
+
+  profile = var.profile
+  application_list = [
+    "app1",
+    "app2",
+    "app3",
+    "subapp/new1app1",
+    "subapp/new1app2",
+    "subapp/new1app3",
+  ]
+  application_name = "org-project"
+  image_config     = var.image_config
+  tags             = {}
+
+  ### optional
+  ##  account_alias        = ""
+  ##  account_id           = ""
+  ##  destination_password = ""
+  ##  destination_username = ""
+  ##  override_prefixes    = {}
+  ##  region               = ""
+  ##  source_password      = ""
+  ##  source_username      = ""
+
+  enable_lifecycle_policy = true
+  lifecycle_policy_all    = true
+  lifecycle_policy_prefix = {
+    repos = [
+      "app1",
+      "app2",
+    ]
+    values = ["dev_", "uat_", "sit_"]
+  }
+  lifecycle_policy_pattern = {
+    repos = [
+      "subapp/new1app1",
+      "subapp/new1app2",
+    ]
+    values = ["*.rc.*"]
+  }
+  lifecycle_policy_explicit = {
+    repos = [
+      "subapp/new1app3",
+    ]
+    policy = data.aws_ecr_lifecycle_policy_document.pushed.json
+  }
+}
+
+data "aws_ecr_lifecycle_policy_document" "pushed" {
+  rule {
+    priority    = 1
+    description = "keep images tagged test, last push 28 days ago"
+
+    selection {
+      tag_status       = "tagged"
+      tag_pattern_list = ["*test*"]
+      count_type       = "sinceImagePushed"
+      count_number     = 28
+      count_unit       = days
+    }
+  }
+}
diff --git a/examples/lifecycle-policy/variables.tf b/examples/lifecycle-policy/variables.tf
@@ -0,0 +1,24 @@
+variable "application_name" {
+  description = "Appliication name, usually {org}-{project}, which is likely a prefix to the EKS cluster name"
+  type        = string
+}
+
+variable "application_list" {
+  description = "List of application repositories to create for /{application_name}/{image_name} for those not in image_config"
+  type        = list(string)
+  default     = []
+}
+
+variable "image_config" {
+  description = "List of image configuration objects to copy from SOURCE to DESTINATION"
+  type = list(object({
+    name            = string,
+    tag             = string,
+    dest_path       = string,
+    source_registry = string,
+    source_image    = string,
+    source_tag      = string,
+    enabled         = bool,
+  }))
+  default = []
+}
diff --git a/main.tf b/main.tf
@@ -80,7 +80,106 @@
 * ## profile
 * This variable is required because this module calls a script, and it uses `aws` CLI commands.  As such, it needs to set the `AWS_PROFILE` environment
 * variable to call the script properly.
+*
+* ## enable_lifecycle_policy 
+* 
+* This enables or disables setting of ECR lifecycle policies for the associated respositories.  It is
+* false by default, but this may change at a later date.
+* 
+* ```hcl
+*   enable_lifecycle_policy = true
+* ```
+* 
+* To effectively enable polices, one of the other `lifecycle_policy_*` variables must be set:
+* 
+* * lifecycle_policy_all 
+* * lifecycle_policy_prefix
+* * lifecycle_policy_pattern
+* * lifecycle_policy_explicit
+* 
+* ## lifecycle_policy_all 
+* 
+* If lifecyle policies are enabled (`enable_lifecycle_policy=true`), this will use a default lifecycle policy (any), keeping only 5 copies of an image within all repositories created
+* with this module (`application_list`), excluding those in from `image_config`.
+* 
+* This will exclude repositories defined in all of the other `lifecycle_policy_*` variables, which will have their own policy applied.
+* 
+* * lifecycle_policy_prefix
+* * lifecycle_policy_pattern
+* * lifecycle_policy_explicit
+* 
+* ## lifecycle_policy_prefix
+* 
+* This is an object with several keys:
+* 
+* * repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the prefixes defined in `values`
+* * values: a list of prefixes
+* * count: the number of images to keep (default is 5)
+* 
+* ```hcl
+*   lifecycle_policy_prefix = {
+*     repos = [
+*       "app1",
+*       "app2",
+*     ]
+*     values = ["dev_", "uat_", "sit_"]
+*     count = 5
+*   }
+* ```
 * 
+* This will set a policy on repos `app1` and `app2`, with 4 rules , one of which is untagged images (keep 5), and the others are the prefix `dev_`, `uat_`, and `sit_` (keep 5 of each prefix).
+* Note this is not the same as a prefix list (see the [docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html)) in a single rule,
+* which would have to match ALL the prefixes. To do more complicated policies, use the [explicit](#lifecycle-policy-explicit) variable.
+* 
+* ## lifecycle_policy_pattern 
+* 
+* This is very much like the prefix policy above, but for a pattern.  It is an object with several keys:
+* 
+* * repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the patterns defined in `values`
+* * values: a list of prefixes
+* * count: the number of images to keep (default is 5)
+* 
+* ```hcl
+*   lifecycle_policy_pattern = {
+*     repos = [
+*       "subapp/new1app1",
+*       "subapp/new1app2",
+*     ]
+*     values = ["*.rc.*"]
+*   }
+* ```
+* 
+* This would create a policy on 
+* This will set a policy on repos `sub app/newapp1` and `subapp/newapp2`, with 2 rules , one of which is untagged images (keep 5), and the other looking for a pattern of `*.rc.*` (keeping 5).
+* Note this is not the same as a pattern list (see the [docs](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html)) in a single rule,
+* which would have to match ALL the patterns. To do more complicated policies, use the [explicit](#lifecycle-policy-explicit) variable.
+* 
+* ## lifecycle_policy_explicit 
+* 
+* This one allows more control, but you have to write your own policy.  See the [Terraform resource doc](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ecr_lifecycle_policy_document)
+* for information on how.  Specify the list of repos, and then the explicit policy to apply. Note this does not allow for more than one set of custom policies.  It is not expected that this will
+* get much use.
+* 
+* This is an object with several keys:
+* 
+* * repos: list of repositories (from the `application_list`) to apply a lifecycle policy with the policy defined in `policy`
+* * policy: a formatted ECR lifecycle policy JSON string
+* 
+* ```
+*   lifecycle_policy_explicit = {
+*     repos = [
+*       "subapp/new1app3",
+*     ]
+*     policy = data.aws_ecr_lifecycle_policy_document.pushed.json
+*   }
+* }
+* 
+* This will apply a custom policy `data.aws_ecr_lifecycle_policy_document.pushed.json` to the repo `subapp/new1app3`.
+* 
+* # Examples
+* * [Simple](examples/simple)
+* * [Lifecycle Policy](examples/lifecycle-policy)
+*
 * # Caveats
 * Currently, a destroy of the images (null_resources) does **NOT** remove the repository. That is a work in progress.
 */

diff --git a/variables.tf b/variables.tf
@@ -116,12 +116,10 @@ variable "lifecycle_policy_pattern" {
 variable "lifecycle_policy_explicit" {
   description = "Object with settings for selecting repositories to apply a policy for an explicit policy.  Select repo list and number of images to keep (default: 5), and a policy defined using `data.aws_ecr_lifecycle_policy_document.{name}.json'"
   type = object({
-    count  = optional(number, 5)
     repos  = list(string)
     policy = string
   })
   default = {
-    count  = 5
     repos  = []
     policy = null
   }