Menu
AWS CodeDeploy
User Guide (API Version 2014-10-06)

Automatically Deregister an On-Premises Instance

Typically, you deregister an on-premises instance after you're no longer planning to deploy to it. When you deregister an on-premises instance, even though the on-premises instance might be part of a deployment group's on-premises instance tags, the on-premises instance will not be included in any deployments. You can use the AWS CLI to deregister on-premises instances.

Note

You cannot use the AWS CodeDeploy console to deregister an on-premises instance. Also, deregistering an on-premises instance does not disassociate any on-premises instance tags that are associated with the on-premises instance. It does not uninstall the AWS CodeDeploy agent from the on-premises instance. It does not remove the on-premises instance configuration file from the on-premises instance.

To use the AWS CodeDeploy console to perform some (but not all) of the activities in this section, see the AWS CodeDeploy console section of Manually Deregister an On-Premises Instance.

To manually disassociate any associated on-premises instance tags, see Manually Remove On-Premises Instance Tags from an On-Premises Instance.

To automatically uninstall the AWS CodeDeploy agent and remove the configuration file from the on-premises instance, see Automatically Uninstall the AWS CodeDeploy Agent and Remove the Configuration File from an On-Premises Instance.

To manually uninstall only the AWS CodeDeploy agent from the on-premises instance, see Managing AWS CodeDeploy Agent Operations.

Use the AWS CLI to call the deregister command, specifying:

  • The name that uniquely identifies the on-premises instance to AWS CodeDeploy (with the --instance-name option).

  • Optionally, whether to delete the IAM user associated with the on-premises instance (with the --delete-iam-user option, the default). If you do not want to delete the IAM user associated with the on-premises instance, specify the --no-delete-iam-user option.

  • Optionally, the AWS region where the on-premises instance was registered with AWS CodeDeploy (with the --region option). This must be one of the supported regions listed in Region and Endpoints in the AWS General Reference (for example, us-west-2). If this option is not specified, the default AWS region associated with the calling IAM user will be used.

For example:

Copy
aws deploy deregister --instance-name AssetTag12010298EX --delete-iam-user --region us-west-2

The deregister command does the following:

  1. Deregisters the on-premises instance with AWS CodeDeploy.

  2. If specified, deletes the IAM user associated with the on-premises instance.

After you deregister an on-premises instance, you cannot create a replacement on-premises instance with the same name or the same associated IAM user name until AWS CodeDeploy deletes its records about the deregistered on-premises instance. This typically takes about 24 hours.

If this command encounters any errors, an error message appears, describing how you can manually complete the remaining steps. Otherwise, a success message appears, describing how to call the uninstall command.