From 02983419d6a6c55fb456caf0b78e4ec0f26c2407 Mon Sep 17 00:00:00 2001 From: badra001 Date: Wed, 3 Jul 2024 14:47:05 -0400 Subject: [PATCH] update doc, add example --- README.md | 104 ++++++++++++++++++++++++- examples/lifecycle-policy/images.tf | 64 +++++++++++++++ examples/lifecycle-policy/variables.tf | 24 ++++++ main.tf | 99 +++++++++++++++++++++++ variables.tf | 2 - 5 files changed, 289 insertions(+), 4 deletions(-) create mode 100644 examples/lifecycle-policy/images.tf create mode 100644 examples/lifecycle-policy/variables.tf diff --git a/README.md b/README.md index 15cc460..55de724 100644 --- 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. | [image\_config](#input\_image\_config) | List of image configuration objects to copy from SOURCE to DESTINATION | 
list(object({
    name            = string,
    tag             = string,
    dest_path       = string,
    source_registry = string,
    source_image    = string,
    source_tag      = string,
    enabled         = bool,
  }))
| `[]` | no | | [lifecycle\_policy\_all](#input\_lifecycle\_policy\_all) | Flag to enable the same default policy (any, count of 5) if true | `bool` | `false` | no | | [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). | 
object({
    repos = list(string)
    count = optional(number, 5)
  })
| 
{
  "count": 5,
  "repos": []
}
| no | -| [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'` | 
object({
    count  = optional(number, 5)
    repos  = list(string)
    policy = string
  })
| 
{
  "count": 5,
  "policy": null,
  "repos": []
}
| no | +| [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'` | 
object({
    repos  = list(string)
    policy = string
  })
| 
{
  "policy": null,
  "repos": []
}
| no | | [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). | 
object({
    count  = optional(number, 5)
    repos  = list(string)
    values = list(string)
  })
| 
{
  "count": 5,
  "repos": [],
  "values": []
}
| no | | [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). | 
object({
    count  = optional(number, 5)
    repos  = list(string)
    values = list(string)
  })
| 
{
  "count": 5,
  "repos": [],
  "values": []
}
| no | | [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 new file mode 100644 index 0000000..db67d90 --- /dev/null +++ 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 new file mode 100644 index 0000000..5ad9660 --- /dev/null +++ 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 index 381449b..cfc50d6 100644 --- 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 index 0000abd..38aaf41 100644 --- 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 }