Connecting AWS

Zynnode connects to AWS by asking AWS CloudFormation to create the resources Zynnode needs in your AWS account. You do not need to run terminal commands or create long-lived AWS access keys.

The setup flow opens a CloudFormation stack in AWS. You review the stack, acknowledge that it creates IAM resources, create it, and wait for the stack to finish. When the stack completes, a callback Lambda notifies Zynnode so the AWS connection can be saved.

What the AWS connection creates

The CloudFormation template creates these resources:

The stack must be created by an AWS user or role that can create IAM roles and Lambda functions.

Before you start

Make sure you are signed in to the correct AWS account before creating the stack. If the wrong account is selected in the AWS console, the connection may be created in the wrong account or the stack may fail because you have different permissions there.

The AWS user or role creating the stack needs permission to:

• create and manage the CloudFormation stack
• create IAM roles
• attach inline policies to IAM roles
• tag IAM roles
• pass an IAM role to Lambda
• create and invoke the callback Lambda function
• create CloudWatch log groups and streams for the Lambda

If you are not an AWS admin, ask your AWS account admin to either run the CloudFormation stack for you or grant the required permissions before you start.

Recommended setup option

The simplest option is for an AWS administrator to run the CloudFormation stack from the Zynnode connection flow.

Use this option when:

• you are not comfortable changing IAM permissions
• the AWS account is managed by a company or client
• you received a permission error while creating the stack
• your organization requires admins to approve new IAM roles

The AWS admin should sign in, open the Zynnode connection flow, review the stack, acknowledge IAM resource creation, and create the stack.

Minimum permissions for the stack creator

If an AWS admin wants to grant a scoped policy instead of using full administrator access, the stack creator needs permissions like these.

Replace 123456789012 with your real AWS account ID.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowZynnodeCloudFormationStackManagement",
      "Effect": "Allow",
      "Action": [
        "cloudformation:CreateStack",
        "cloudformation:DescribeStacks",
        "cloudformation:DescribeStackEvents",
        "cloudformation:DeleteStack"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowZynnodeIamRoleSetup",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:GetRole",
        "iam:DeleteRole",
        "iam:PutRolePolicy",
        "iam:DeleteRolePolicy",
        "iam:PassRole",
        "iam:TagRole",
        "iam:UntagRole"
      ],
      "Resource": "arn:aws:iam::123456789012:role/*"
    },
    {
      "Sid": "AllowZynnodeCallbackLambdaSetup",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:GetFunction",
        "lambda:DeleteFunction",
        "lambda:InvokeFunction"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowZynnodeCallbackLambdaLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

This is wrong for the Zynnode CloudFormation stack:

"Resource": "arn:aws:iam::123456789012:user/*"

Use role resources instead:

"Resource": "arn:aws:iam::123456789012:role/*"

Step-by-step setup

ProodcuIntegrationRole-zynnode-stacking

zynnode-stacking-CallbackLambdaRole-GMiCR3VIqiwy

I acknowledge that AWS CloudFormation might create IAM resources.

CREATE_COMPLETE

Troubleshooting

iam:CreateRole permission error

If CloudFormation fails with an error like this:

User: arn:aws:iam::123456789012:user/CodingPastor is not authorized to perform: iam:CreateRole on resource: arn:aws:iam::123456789012:role/zynnode-stacking-CallbackLambdaRole-GMiCR3VIqiwy because no identity-based policy allows the iam:CreateRole action

The root issue is:

The AWS user creating the stack does not have permission to create IAM roles.

AWS may show this as a tagging error:

Encountered a permissions error performing a tagging operation, please add required tag permissions.
HandlerErrorCode: UnauthorizedTaggingOperation

That message can be confusing. In the detailed error, the real denied action may still be:

iam:CreateRole

To fix it, ask the AWS admin to grant the stack creator role permissions on IAM roles, especially:

• iam:CreateRole
• iam:PutRolePolicy
• iam:PassRole
• iam:TagRole
• iam:UntagRole
• iam:GetRole
• iam:DeleteRole
• iam:DeleteRolePolicy

The policy must allow role resources:

"Resource": "arn:aws:iam::123456789012:role/*"

It is not enough to allow only user resources:

"Resource": "arn:aws:iam::123456789012:user/*"

Policy allows iam:* but the stack still fails

If the AWS admin says they already granted iam:*, check the policy resource.

This policy does not allow creating roles:

{
  "Effect": "Allow",
  "Action": "iam:*",
  "Resource": "arn:aws:iam::123456789012:user/*"
}

It only allows IAM actions on IAM users. Zynnode needs IAM role permissions.

Use this instead:

{
  "Effect": "Allow",
  "Action": "iam:*",
  "Resource": "arn:aws:iam::123456789012:role/*"
}

For a more restricted policy, use the minimum permissions listed earlier in this guide.

Role cannot be found during rollback

After a failed stack creation, AWS may show messages like:

The role with name ProodcuIntegrationRole-zynnode-stacking cannot be found.
The role with name zynnode-stacking-CallbackLambdaRole-GMiCR3VIqiwy cannot be found.

These messages usually happen during rollback. They are cleanup messages, not the root cause.

The important event is the first CREATE_FAILED event. In the permissions case, that event usually says the user is not authorized to perform iam:CreateRole.

What to do:

1. Wait for the stack rollback to finish.
2. Ask the AWS admin to fix the IAM permissions.
3. Delete the failed stack if AWS leaves it in the CloudFormation console.
4. Start the Zynnode AWS connection flow again.

Stack is stuck in rollback

If the stack is in ROLLBACK_IN_PROGRESS, wait for AWS to finish. Do not retry while rollback is still running.

When rollback finishes, the stack may show:

• ROLLBACK_COMPLETE
• DELETE_COMPLETE
• a failed stack that can be manually deleted

After rollback finishes, fix the permission issue and create a new stack from Zynnode.

Callback does not complete

If the CloudFormation stack reaches CREATE_COMPLETE but Zynnode does not show the AWS connection:

1. Open the CloudFormation stack.
2. Check the stack outputs for the role ARN.
3. Open the Lambda function created by the stack.
4. Check the Lambda logs in CloudWatch.
5. Confirm the Lambda can reach the Zynnode callback URL.

The callback URL is generated from the Zynnode backend base URL. If Zynnode is running in a private or temporary environment, the callback URL must be publicly reachable by AWS Lambda.

I want to disconnect AWS

To remove the Zynnode connection from your AWS account:

1. Open the AWS CloudFormation Console.
2. Find the Zynnode stack.
3. Select it and click Delete.
4. In the Zynnode dashboard, remove the AWS connection card.

Message to send to an AWS admin

Use this when asking an AWS admin for help:

We are connecting Zynnode to our AWS account using a CloudFormation stack.

The stack creates IAM roles and a callback Lambda. It failed because my AWS user does not have permission to create IAM roles.

Please either run the CloudFormation stack with an admin AWS role, or grant my AWS user/role permission to create and manage IAM roles under arn:aws:iam::<account-id>:role/*.

Required IAM actions include iam:CreateRole, iam:PutRolePolicy, iam:PassRole, iam:TagRole, iam:UntagRole, iam:GetRole, iam:DeleteRole, and iam:DeleteRolePolicy.

Please make sure the policy applies to role/* resources, not only user/* resources.

Quick checklist

Before retrying a failed AWS connection:

• Confirm you are in the correct AWS account.
• Confirm the failed stack rollback has finished.
• Confirm you have iam:CreateRole on arn:aws:iam::<account-id>:role/*.
• Confirm you have iam:TagRole and iam:UntagRole.
• Confirm you have Lambda creation permissions.
• Delete the failed stack if AWS left one behind.
• Start the Zynnode AWS connection flow again.