How to Unpair the Portainer Agent from the Old Instance and Connect to a New One

Introduction:

Transitioning your Portainer Agent from an old instance to a new one can seem daunting, but it’s a necessary step for maintaining a streamlined and efficient container management system. Whether you’re a small business owner, web developer, or freelancer, this guide will walk you through the process in seven easy steps. By the end, you’ll have your Portainer Agent seamlessly connected to your new instance, ensuring your operations continue smoothly.

Prerequisites

Before starting, ensure you have:

• Access to your old and new Portainer instances (if possible).
• Administrative privileges on both Portainer instances.
• The Portainer Agent running on your Docker environment.
• Basic knowledge of Docker and Portainer.

Step-by-Step Guide to Unpair and Reconnect the Portainer Agent

1. Alternative Step if No Access to Old Portainer Instance

• If you can’t access the old Portainer instance, simply restart the Portainer Agent on the remote instance:

  sudo docker restart portainer_agent

• The agent does not retain persistent connection information, so this restart will effectively unpair it from the old instance.
• Hint: If you are following this step, move directly to step 8 to verify the connection with the new instance. Otherwise, proceed to step 2 for a thorough unpairing process.

2. Log in to the Old Portainer Instance

• Access your old Portainer instance.
• Navigate to the “Endpoints” section.
• Identify the endpoint associated with the Portainer Agent you want to unpair.

3. Remove the Old Endpoint

• Select the endpoint and click on “Manage Endpoint”.
• Choose “Delete” to remove the endpoint from the old instance.
• Confirm the deletion when prompted.

4. Stop the Portainer Agent

• SSH into the server running the Portainer Agent.
• Use Docker commands to stop the agent:

  docker stop portainer_agent

5. Remove the Portainer Agent

• Remove the Portainer Agent container to ensure a fresh start:

  docker rm portainer_agent

6. Deploy the Portainer Agent for the New Instance

• Download the Portainer Agent deployment script for the new instance.
• Run the deployment script with the correct configuration for the new instance:

  docker run -d -p 9001:9001 \ --name portainer_agent \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ portainer/agent

7. Configure the Agent with the New Portainer Instance

• Log in to your new Portainer instance.
• Navigate to the “Endpoints” section and add a new endpoint.
• Select “Agent” as the endpoint type.
• Provide the necessary details such as the IP address of the agent host and the agent port (default is 9001).

8. Verify the Connection

• Ensure the new endpoint is listed in the new Portainer instance.
• Verify that the connection status is healthy.
• Check if all containers and services are correctly displayed.

Conclusion

By following these seven steps, you’ve successfully unpaired your Portainer Agent from the old instance and connected it to a new one. This process ensures that your container management remains efficient and up-to-date, paving the way for smoother operations.

FAQ

Can I unpair and reconnect multiple agents at once?

• Yes, but you must repeat the steps for each agent.

What if the agent doesn’t appear in the new instance?

• Check your network settings and ensure the agent is running on the correct port.

Will this process cause downtime?

• Minimal downtime is expected, primarily during the agent stop/start phases.

Is it necessary to remove the agent container?

• Yes, to ensure no residual configurations interfere with the new setup.

What if I encounter permission issues?

• Ensure you have administrative rights on both Portainer instances and Docker environments.