docs: update ECR documentation

.github/workflows/codeartifact-repo.yaml

@@ -16,6 +16,8 @@ on:
 jobs:
   test-and-verify:
     runs-on: ubuntu-24.04
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

.github/workflows/easy-ecr.yaml

@@ -16,6 +16,8 @@ on:
 jobs:
   test-and-verify:
     runs-on: ubuntu-24.04
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

.terraform-docs.yaml

@@ -53,13 +53,6 @@ output:
     {{ .Content }}
     <!-- END_TF_DOCS -->
 
-# output-values:
-#   enabled: false
-#   from: ""
-
-# sort:
-#   enabled: true
-#   by: name
 
 settings:
   anchor: true

easy-ecr/README.md

@@ -28,27 +28,27 @@ This Terraform module provides production-ready ECR repository for storing conta
 | Name | Type |
 |------|------|
 | [aws_ecr_account_setting.account_scan_config](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_account_setting) | resource |
-|**Description:**  ||
+|**Description:** Configures default registry scan setting. By default, `BASIC` scan type is used wit `AWS_NATIVE` configuration. ||
 | [aws_ecr_lifecycle_policy.repo_lifecycle_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_lifecycle_policy) | resource |
-|**Description:**  ||
+|**Description:** Lifecycle policy applied to images inside the repository ||
 | [aws_ecr_pull_through_cache_rule.custom_pullthrough_cache_rule](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_pull_through_cache_rule) | resource |
-|**Description:**  ||
+|**Description:** Custom user-defined pullthrough cache rules. ||
 | [aws_ecr_pull_through_cache_rule.default_pullthrough_cache_rule](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_pull_through_cache_rule) | resource |
-|**Description:**  ||
+|**Description:** Defines default pullthrough cache rules from well-known sources (Docker Hub, Github, Quay etc). By default, all cache rules are disabled. ||
 | [aws_ecr_registry_policy.registry_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_registry_policy) | resource |
-|**Description:**  ||
+|**Description:** IAM policy to be applied to ECR registry. ||
 | [aws_ecr_registry_scanning_configuration.registry_scan_config](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_registry_scanning_configuration) | resource |
-|**Description:**  ||
+|**Description:** Configures registry scanning configuration. ||
 | [aws_ecr_replication_configuration.replication_config](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_replication_configuration) | resource |
 |**Description:** Defines registry replication configuration. Current implementation allows only replication withing the same AWS account. It is possible to define rule filters for replication. ||
 | [aws_ecr_repository.ecr_private_repo](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_repository) | resource |
-|**Description:**  ||
+|**Description:** Private repository to create. Only created if variable `visibility` is set to `PRIVATE`. ||
 | [aws_ecr_repository_policy.repo_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecr_repository_policy) | resource |
-|**Description:**  ||
+|**Description:** IAM policy to be applied to ECR repository. ||
 | [aws_ecrpublic_repository.ecr_public_repo](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecrpublic_repository) | resource |
-|**Description:**  ||
+|**Description:** Public repository to create. Only created if variable `visibility` is set to `PUBLIC`. ||
 | [aws_ecrpublic_repository_policy.public_repo_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecrpublic_repository_policy) | resource |
-|**Description:**  ||
+|**Description:** IAM policy applied to public repository. ||
 | [aws_iam_role.repo_push_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
 |**Description:** Role which allows read/write access to repository ||
 | [aws_iam_role.repo_read_only_role](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
@@ -58,7 +58,7 @@ This Terraform module provides production-ready ECR repository for storing conta
 | [aws_iam_role_policy.read_only_role_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |
 |**Description:** IAM policy for role allowing read-only (pull) access to repository ||
 | [aws_kms_key.domain_encryption_key](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource |
-|**Description:**  ||
+|**Description:** KMS encryption for repository domain. Created if variable `use_default_ecnryption_key` is false and no KMS key ARN provided ||
 
 ## Inputs
 
@@ -109,6 +109,37 @@ Examples configuration for using the module:
 
 module "easy_ecr" {
     source = ""https://github.com/bitshifted/cloud-tools//easy-ecr?ref=easy-ecr-<current version>"
+
+    # name of repository to create
+    repository_name = "test-private-repo"
+    # whether image tags are MUTABLE (true) or IMMUTBLE (false)
+    image_tag_mutable = false
+    # exclusion filter to apply to image tags
+    mutability_exclusion_filters = ["dev*"]
+
+    # custom registry policy
+    registry_policy_path = "./registry-policy.json"
+
+    # custom repository -policy
+    repo_policy_path = "./repo-policy.json"
+
+    # pullthrough cache settings
+   # enable pull through cache for AWS ECR public registry
+   aws_public_pullthrough_cache_rule = {
+    enabled = true
+  }
+
+  # principal ARNs listed here will have permissions to assume the role which allows pulling images from repository
+  pull_only_principals = ["arn:aws:iam::12345667:user/user1"]
+
+  # principal ARNs listed here will have permissions to assume the role which allows publishing images
+  push_principals = ["arn:aws:iam::12345667:user/user1
+
+  # tags applied to all created resources
+  tags = {
+    "Environment" = "Test"
+    "Project" = "EasyEcrModule"
+  }
 }
 ```
 <!-- END_TF_DOCS -->

easy-ecr/cache.tf

@@ -27,6 +27,8 @@ locals {
 
 }
 
+# Defines default pullthrough cache rules from well-known sources (Docker Hub, Github, Quay etc). By default, all
+# cache rules are disabled.
 resource "aws_ecr_pull_through_cache_rule" "default_pullthrough_cache_rule" {
   for_each                   = { for k, v in local.default_cache_rules : k => v if v.enabled == true }
   region                     = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region
@@ -37,6 +39,7 @@ resource "aws_ecr_pull_through_cache_rule" "default_pullthrough_cache_rule" {
   upstream_repository_prefix = each.value.upstream_repository_prefix
 }
 
+# Custom user-defined pullthrough cache rules.
 resource "aws_ecr_pull_through_cache_rule" "custom_pullthrough_cache_rule" {
   for_each                   = { for k, v in var.pullthrough_cache_rules : k => v }
   region                     = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region

easy-ecr/docs/examples.md

@@ -6,5 +6,36 @@ Examples configuration for using the module:
 
 module "easy_ecr" {
     source = ""https://github.com/bitshifted/cloud-tools//easy-ecr?ref=easy-ecr-<current version>"
+
+    # name of repository to create
+    repository_name = "test-private-repo"
+    # whether image tags are MUTABLE (true) or IMMUTBLE (false)
+    image_tag_mutable = false
+    # exclusion filter to apply to image tags
+    mutability_exclusion_filters = ["dev*"]
+
+    # custom registry policy
+    registry_policy_path = "./registry-policy.json"
+
+    # custom repository -policy
+    repo_policy_path = "./repo-policy.json"
+
+    # pullthrough cache settings
+   # enable pull through cache for AWS ECR public registry
+   aws_public_pullthrough_cache_rule = {
+    enabled = true
+  }
+
+  # principal ARNs listed here will have permissions to assume the role which allows pulling images from repository
+  pull_only_principals = ["arn:aws:iam::12345667:user/user1"]
+
+  # principal ARNs listed here will have permissions to assume the role which allows publishing images
+  push_principals = ["arn:aws:iam::12345667:user/user1
+
+  # tags applied to all created resources
+  tags = {
+    "Environment" = "Test"
+    "Project" = "EasyEcrModule"
+  }
 }
 ```

easy-ecr/main.tf

@@ -11,6 +11,7 @@ locals {
 
 data "aws_region" "current_region" {}
 
+# Private repository to create. Only created if variable `visibility` is set to `PRIVATE`.
 resource "aws_ecr_repository" "ecr_private_repo" {
   count                = var.visibility == "PRIVATE" ? 1 : 0
   name                 = var.repository_name
@@ -39,6 +40,7 @@ resource "aws_ecr_repository" "ecr_private_repo" {
   tags = var.tags
 }
 
+# Public repository to create. Only created if variable `visibility` is set to `PUBLIC`.
 resource "aws_ecrpublic_repository" "ecr_public_repo" {
   count           = var.visibility == "PUBLIC" ? 1 : 0
   repository_name = var.repository_name
@@ -56,6 +58,7 @@ resource "aws_ecrpublic_repository" "ecr_public_repo" {
   tags = var.tags
 }
 
+# KMS encryption for repository domain. Created if variable `use_default_ecnryption_key` is false and no KMS key ARN provided
 resource "aws_kms_key" "domain_encryption_key" {
   count               = local.should_create_kms_key ? 1 : 0
   description         = "KMS key for ECR repository domain ${var.repository_name}"

easy-ecr/policies.tf

@@ -6,26 +6,30 @@ locals {
   apply_default_lifecycle_policy = var.use_default_image_lifecycle_policy && var.image_lifecycle_policy_path == null
 }
 
+# IAM policy to be applied to ECR registry. 
 resource "aws_ecr_registry_policy" "registry_policy" {
   count  = var.registry_policy_path != null ? 1 : 0
   region = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region
   policy = file(var.registry_policy_path)
 }
 
+# IAM policy to be applied to ECR repository.
 resource "aws_ecr_repository_policy" "repo_policy" {
   count      = var.repo_policy_path != null ? 1 : 0
   region     = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region
   repository = aws_ecr_repository.ecr_private_repo[0].name
   policy     = file(var.repo_policy_path)
 }
 
+# Lifecycle policy applied to images inside the repository
 resource "aws_ecr_lifecycle_policy" "repo_lifecycle_policy" {
   count      = local.use_any_lifecycle_policy ? 1 : 0
   region     = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region
   repository = aws_ecr_repository.ecr_private_repo[0].name
   policy     = local.apply_default_lifecycle_policy ? file("${path.module}/default-lifecycle-policy.json") : file(var.image_lifecycle_policy_path)
 }
 
+# IAM policy applied to public repository.
 resource "aws_ecrpublic_repository_policy" "public_repo_policy" {
   count           = var.public_repo_policy_path != null ? 1 : 0
   region          = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region

easy-ecr/scan_config.tf

@@ -2,11 +2,13 @@
 # SPDX-License-Identifier: MPL-2.0
 
 
+# Configures default registry scan setting. By default, `BASIC` scan type is used wit `AWS_NATIVE` configuration.
 resource "aws_ecr_account_setting" "account_scan_config" {
   name  = var.default_account_scan_config.name
   value = var.default_account_scan_config.value
 }
 
+# Configures registry scanning configuration.
 resource "aws_ecr_registry_scanning_configuration" "registry_scan_config" {
   region    = var.ecr_region != null ? var.ecr_region : data.aws_region.current_region.region
   scan_type = var.registry_scan_configuration.type