renovate/lib/modules/datasource/aws-machine-image/readme.md

!!! warning
  This datasource is experimental.
  Its syntax and behavior may change at any time!

This datasource returns the latest [Amazon Machine Image](https://docs.aws.amazon.com/en_en/AWSEC2/latest/UserGuide/AMIs.html) via the AWS API.

See [Calling AWS Services from Renovate](../../../calling-aws-services.md) for how to configure your credentials.

You can also provide credentials specifically for this datasource with a `hostRules` entry.
Set `hostType` to `aws-machine-image`, `username` to the access key ID, `password` to the secret access key, and optionally `token` to the session token:

```json
{
  "hostRules": [
    {
      "hostType": "aws-machine-image",
      "username": "access-key-id",
      "password": "secret-access-key",
      "token": "session-token"
    }
  ]
}
```

These credentials only apply to Amazon Machine Image lookups.
When this host rule is absent or incomplete, Renovate uses the default AWS credential provider chain.

Read the [Developer guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/configuring-the-jssdk.html) for more information on configuration options.

The least IAM privileges required for this datasource are:

```json {configType=none}
{
  "Sid": "AllowEc2ImageLookup",
  "Effect": "Allow",
  "Action": ["ec2:DescribeImages"],
  "Resource": "*"
}
```

Read the [AWS IAM Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonec2.html) for more information.

Because there is no general `packageName`, you have to use the [describe images filter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ec2/interfaces/describeimagescommandinput.html#filters) as minified JSON as a `packageName`.

Example:

```yaml
# Getting the latest official EKS image from AWS (account '602401143452' for eu-central-1) for EKS 1.21 (name matches 'amazon-eks-node-1.21-*') would look as a describe images filter like:

[
  {
    "Name": "owner-id",
    "Values": [ "602401143452" ]
  },
  {
    "Name": "name",
    "Values": [ "amazon-eks-node-1.21-*" ]
  }
]

# In order to use it with this datasource, you have to minify it:

[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]
```

At the moment, this datasource has no "manager".
You have to use the custom manager for this.

**Usage Example**

Here's an example of using the custom manager:

```javascript
module.exports = {
  customManagers: [
    {
      customType: 'regex',
      managerFilePatterns: ['/.*/'],
      matchStrings: [
        '.*amiFilter=(?<packageName>.*?)\n(.*currentImageName=(?<currentDigest>.*?)\n)?(.*\n)?.*?(?<depName>[a-zA-Z0-9-_:]*)[ ]*?[:|=][ ]*?["|\']?(?<currentValue>ami-[a-z0-9]{17})["|\']?.*',
      ],
      datasourceTemplate: 'aws-machine-image',
      versioningTemplate: 'aws-machine-image',
    },
  ],
};
```

Or as JSON:

```yaml
{
  'customManagers':
    [
      {
        'customType': 'regex',
        'managerFilePatterns': ['/.*/'],
        'matchStrings':
          [
            ".*amiFilter=(?<packageName>.*?)\n(.*currentImageName=(?<currentDigest>.*?)\n)?(.*\n)?.*?(?<depName>[a-zA-Z0-9-_:]*)[ ]*?[:|=][ ]*?[\"|']?(?<currentValue>ami-[a-z0-9]{17})[\"|']?.*",
          ],
        'datasourceTemplate': 'aws-machine-image',
        'versioningTemplate': 'aws-machine-image',
      },
    ],
}
```

**Note about `currentImageName`:**

The optional `currentImageName` comment is automatically updated by Renovate to track the actual AMI name corresponding to the AMI ID.
This provides human-readable context about which image version is being used.
When Renovate finds a newer AMI, it will update both the AMI ID and the `currentImageName` comment.

This would match every file, and would recognize the following lines:

```yaml
# With AMI name mentioned in the comments
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]
# currentImageName=amazon-eks-node-1.21-v20240703
my_ami1: ami-02ce3d9008cab69cb

# Only AMI, no name mentioned
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
# currentImageName=amazon-eks-node-1.20-v20240615
my_ami2: ami-0083e9407e275acf2

# Using custom aws profile and region
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]},{"profile":"test","region":"eu-central-1"}]
# currentImageName=amazon-eks-node-1.20-v20240615
ami = "ami-0083e9407e275acf2"

# Without currentImageName comment (also works!)
# amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.19-*"]}]
my_ami3: ami-0a1b2c3d4e5f6g7h8
```

```typescript
const myConfigObject = {
  // With AMI name mentioned in the comments
  // amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.21-*"]}]
  // currentImageName=amazon-eks-node-1.21-v20240703
  my_ami1: 'ami-02ce3d9008cab69cb',
};

/**
 * AMI with name tracked in comment
 * amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
 * currentImageName=amazon-eks-node-1.20-v20240615
 */
const my_ami2 = 'ami-0083e9407e275acf2';

/**
 * Without currentImageName comment
 * amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.19-*"]}]
 */
const my_ami3 = 'ami-0a1b2c3d4e5f6g7h8';
```

```hcl
resource "aws_instance" "web" {

    # AMI with name tracked in comment
    # amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.20-*"]}]
    # currentImageName=amazon-eks-node-1.20-v20240615
    ami = "ami-0083e9407e275acf2"

    count = 2
    source_dest_check = false

    connection {
        user = "root"
    }
}

resource "aws_instance" "app" {
    # Without currentImageName comment
    # amiFilter=[{"Name":"owner-id","Values":["602401143452"]},{"Name":"name","Values":["amazon-eks-node-1.19-*"]}]
    ami = "ami-0a1b2c3d4e5f6g7h8"

    count = 1
}
```