Recover Instance by Checking Root Volume

This document explains how to recover a Linux instance when SSH access is unavailable by checking the root volume and creating a new instance based on it.

• SSH Connection Error
  • Step 1. Check Existing Instance Information
  • Step 2. Create and Restore a Snapshot of the Root Volume
  • Step 3. Prepare a Temporary Instance and Attach the Restored Volume
  • Step 4. Mount the Restored Volume to the Debug Instance, Check the Volume, and Fix the Issue
  • Step 5. Detach the Volume from the Debug Instance
  • Step 6. Create an Image from the Detached Volume
  • Step 7. Create a New Instance
  • Step 8. Verify SSH Access to New Instance and Perform Final Checks

---

SSH Connection Error

When trying to connect to a Linux instance via SSH, you may encounter one of the following error messages:

• connect to host <server IP> port xx: No Route to host
• ssh: connect to host <server IP> port xx: Operation timed out

These errors may be caused by issues such as incorrect internal network settings, corrupted file systems, or an unresponsive SSH daemon. Since direct access to the instance is not possible, you must detach the root volume and connect it to another instance for inspection.

▶️ Resolution Steps

This guide uses OpenAPI, but the same actions can be performed via the Kakao Cloud Console.
To use OpenAPI, complete the prerequisites described in Getting Started with OpenAPI.

You can efficiently recover from SSH connection issues by detaching the root volume from the faulty instance, attaching it to a temporary instance for inspection and repair, creating an image from the modified volume, and deploying a new instance. This allows for remote recovery without console access.

---

Step 1. Check Existing Instance Information

Use the Get instance OpenAPI to obtain the instance ID, root volume ID, instance type, security groups, and keypair.

Request

Create snapshot Request Syntax

curl -X GET 'https://bcs.kr-central-2.kakaocloud.com/api/v1/instances/${INSTANCE_ID}' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: ${API_TOKEN}'

Variable	Descriptions
INSTANCE_ID🖌︎	existing instance ID
API_TOKEN🖌︎	API authentication token

Information to retrieve from the response

Item	Response Body Field
Instance ID	instance.id
Root Volume ID	Check the instance.attached_volumes.id value where is_root=true
Root Volume Size	Check the instance.attached_volumes.size value where is_root=true
Instance Flavor ID	instance.flavor.id
Security Group Name	instance.security_groups.name
Keypair Name	instance.key_name
Availability Zone	instance.availability_zone

Step 2. Create and Restore a Snapshot of the Root Volume

1. Create a snapshot of the problematic root volume using the Create snapshot OpenAPI.

Request

Create snapshot Request Syntax

  curl -X POST 'https://volume.kr-central-2.kakaocloud.com/api/v1/volumes/${VOLUME_ID}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Auth-Token: ${API_TOKEN}' \
  -d '{
    "snapshot": {
      "name": "${SNAPSHOT_NAME}",
      "description": "${SNAPSHOT_DESC}",
      "is_incremental": false
    }
  }'

Variable	Descriptions
VOLUME_ID🖌︎	Root volume ID
API_TOKEN🖌︎	API authentication token
SNAPSHOT_NAME🖌︎	Snapshot name
SNAPSHOT_DESC🖌︎	Snapshot description

Information to Retrieve from Response

Information	Response Body Field
Snapshot ID	snapshot.id

2. Restore the volume using the Restore snapshot OpenAPI.

   Request

Restore snapshot Request Syntax

  curl -X POST 'https://volume.kr-central-2.kakaocloud.com/api/v1/snapshots/${SNAPSHOT_ID}/restore' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Auth-Token: ${API_TOKEN}' \
  -d '{
    "restore": {
      "name": "${VOLUME_NAME}",
      "availability_zone": "${AVAILABILITY_ZONE}",
      "volume_type_id": "${VOLUME_TYPE_ID}"
    }
  }'

Variable	Descriptions
SNAPSHOT_ID🖌︎	Snapshot ID
API_TOKEN🖌︎	API authentication token
VOLUME_NAME🖌︎	Name of the restored volume
AVAILABILITY_ZONE🖌︎	Availability zone for the restored volume
VOLUME_TYPE_ID🖌︎	Volume type ID

Volume Type ID Lookup

You can retrieve the Volume Type ID using the List volume types OpenAPI.

Response Fields to Extract

Item	Response Body Field
Restored Volume ID	restore.volume_id

Step 3. Prepare a Temporary Instance and Attach the Restored Volume

1. Create a new temporary instance using the Create instance OpenAPI, or prepare an existing instance for inspection.

2. Attach the restored volume from Step 2-2 using the Attach volume OpenAPI.

Request

Attach volume Request Syntax

curl -X POST 'https://bcs.kr-central-2.kakaocloud.com/api/v1/instances/${DEBUG_INSTANCE_ID}/volumes/${RESTORED_VOLUME_ID}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: ${API_TOKEN}' \
-d '{
  "volume": {
    "is_delete_on_termination": ${IS_DELETE_ON_TERMINATION}
  }
}'

Variable	Descriptions
DEBUG_INSTANCE_ID🖌︎	Debug instance ID
RESTORED_VOLUME_ID🖌︎	Restored volume ID
API_TOKEN🖌︎	API authentication token
IS_DELETE_ON_TERMINATION🖌︎	Whether to automatically delete the volume when the instance is deleted — set to true or false depending on your needs

Step 4. Mount the Restored Volume to the Debug Instance, Check the Volume, and Fix the Issue

1. Connect to the debug instance and mount the restored volume. Refer to the Volume Attachment Guide.

2. Check the following:

   • Network Configuration: Verify that the network configuration file has the correct IP address, gateway, and DNS settings.

     • For Ubuntu instances, check files inside the /etc/netplan directory.
     • For RedHat-based (CentOS, Rocky) instances, check files inside the /etc/sysconfig/network-scripts directory.

   • File System Check and Repair: To repair the file system, unmount the volume first. Then use the xfs_repair -n command to detect corruption, followed by xfs_repair to fix and recover corrupted areas.

   • Analyze and Fix Boot Errors: Review the system logs via the Kakao Cloud console. Analyze and resolve boot issues based on error messages encountered during the boot process.

Step 5. Detach the Volume from the Debug Instance

Use the Detach volume OpenAPI to detach the restored volume from the debug instance.

Request

Detach volume Request Syntax

curl -X DELETE 'https://bcs.kr-central-2.kakaocloud.com/api/v1/instances/${DEBUG_INSTANCE_ID}/volumes/${RESTORED_VOLUME_ID}' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: ${API_TOKEN}'

Variable	Descriptions
DEBUG_INSTANCE_ID🖌︎	Debug instance ID
RESTORED_VOLUME_ID🖌︎	Restored volume ID
API_TOKEN🖌︎	API authentication token

Step 6. Create an Image from the Detached Volume

After resolving the issue, create an image based on the restored volume. Use the Create image OpenAPI for this process.

Important Notice for Image Creation

If you create an image from a running instance, data stored in memory may not be fully written to the volume, which can result in data inconsistency.
It is strongly recommended to stop the instance before creating the image.

Request

Create image Request Syntax

curl -X POST 'https://volume.kr-central-2.kakaocloud.com/api/v1/volumes/${RESTORED_VOLUME_ID}/image' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: ${API_TOKEN}' \
-d '{
  "image": {
    "name": "${IMAGE_NAME}",
    "description": "${IMAGE_DESC}"
  }
}'

Variable	Descriptions
RESTORED_VOLUME_ID🖌︎	Restored Volume ID
API_TOKEN🖌︎	API authentication token
IMAGE_NAME🖌︎	Image name
IMAGE_DESC🖌︎	Image description

Response Fields

Information	Response Body Field
Image ID	image.id

Step 7. Create a New Instance

Deploy a new instance based on the image you just created. Use the Create instance OpenAPI to proceed.

Request

Create instance Request Syntax

curl -X POST 'https://bcs.kr-central-2.kakaocloud.com/api/v1/instances' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: ${API_TOKEN}' \
-d '{
  "instance": {
    "name": "${INSTANCE_ID}",
    "description": "${INSTANCE_DESC}",
    "count": 1,
    "image_id": "${IMAGE_ID}",
    "flavor_id": "${FLAVOR_ID}",
    "availability_zone": "${AZ}",
    "subnets": [
      {
        "id": "${SUBNET_ID}"
      }
    ],
    "volumes": [
      {
        "is_delete_on_termination": true,
        "size": ${VOLUME_SIZE},
        "source_type": "image",
        "uuid": "${IMAGE_ID}",
        "type_id": "${VOLUME_TYPE_ID}"
      }
    ],
    "key_name": "${KEY_NAME}",
    "security_groups": [
      {
        "name": "${SG_NAME}"
      }
    ]
  }
}'

Variable	Description
API_TOKEN🖌︎	API authentication token
INSTANCE_ID🖌︎	Name of the new instance
INSTANCE_DESC🖌︎	Description of the instance
IMAGE_ID🖌︎	Image ID created in Step 6
FLAVOR_ID🖌︎	Instance type ID
AZ🖌︎	Availability zone to launch the instance in
SUBNET_ID🖌︎	Subnet ID
VOLUME_SIZE🖌︎	Volume size, should match the original root volume size
VOLUME_TYPE_ID🖌︎	Volume type ID
KEY_NAME🖌︎	Key pair name
SG_NAME🖌︎	Security group name

Note

• Check Subnet ID: List subnets OpenAPI
• Check Volume Type ID: List volume types OpenAPI

Step 8. Verify SSH Access to New Instance and Perform Final Checks

1. Once the new instance is fully booted, verify SSH access:
   SSH Access Verification

   # If using a key pair
   ssh -i ${pem-key-file} ${username}@${server-ip}

2. If the original instance had additional data volumes, reattach them to the new instance using the appropriate OpenAPI.
3. Finally, delete any temporary resources and unnecessary original instances created during the recovery process.