Tạo hoặc import SSH key pair

POST/v2.1/{project_id}/os-keypairs

Tạo mới một key pair hoặc import public key có sẵn. Nếu truyền public_key, key sẽ được import. Nếu bỏ trống, dịch vụ tạo key pair mới và trả về private key một lần duy nhất trong response. Bạn phải lưu trữ an toàn; không thể lấy lại lần nữa.

Source

create-or-import-keypair

Request

Cấu trúc body

Object JSON ở cấp cao nhất phải chứa một object keypair với các thuộc tính bên dưới.

Tham số

project_idstringbắt buộcpath

UUID của project (tenant).

keypairobjectbắt buộcbody

Object bọc các thuộc tính của key pair.

4 trường

namestringbắt buộcbody

Tên key pair (không trùng trong cùng user). Bắt buộc.

public_keystringbody

Public key cần import (ví dụ bắt đầu bằng ssh-rsa, ssh-ed25519, hoặc PEM cho x509). Nếu bỏ trống, hệ thống tạo key pair mới và trả về private_key.

user_idstringbody

User ID sở hữu key pair (chỉ admin mới tạo được cho user khác). Mới trong phiên bản 2.10

typestringbody

Kiểu key: ssh (mặc định) hoặc x509. Mới trong phiên bản 2.2

Request mẫu

Tạo key pair

curl -ks -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: gAAAAA<...>' \
  -H 'X-OpenStack-Nova-API-Version: 2.72' \
  -d '{
    "keypair": {
      "name": "apikey1"
    }
}' \
https://api.vietnix.cloud:8774/v2.1/{project_id}/os-keypairs

Import public key có sẵn (kèm hậu tố mô tả tuỳ chọn)

Bạn có thể thêm mô tả sau key (để ghi chú), miễn là không làm thay đổi nội dung key. Ví dụ dùng hậu tố dạng comment VSTOR-KEY-DESC:Key3 description.

curl -ks -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: gAAAAA<...>' \
  -H 'X-OpenStack-Nova-API-Version: 2.72' \
  -d '{
    "keypair": {
      "name": "apikey2",
      "public_key": "ssh-rsa AAAA<...> VSTOR-KEY-DESC:Key2 description"
    }
}' \
https://api.vietnix.cloud:8774/v2.1/{project_id}/os-keypairs

Thay {project_id} bằng UUID project thực tế của bạn.

Response

Khi thành công, trả về một object keypair.

Trường trong body response

keypairobjectbắt buộc

Object bọc key pair vừa tạo (hoặc vừa import).

7 trường

namestringbắt buộcbody

Tên key pair.

public_keystringbắt buộcbody

Nội dung public key. Với key được tạo tự động, có thể có comment Generated-by-Nova ở cuối.

private_key (chỉ khi được tạo)stringbắt buộcbody

Private key (PEM), chỉ trả về một lần khi không truyền public_key. Phải lưu trữ an toàn.

fingerprintstringbắt buộcbody

Fingerprint MD5 (hex, phân tách bằng dấu hai chấm).

user_idstringbắt buộcbody

User ID sở hữu key pair.

created_atstringbắt buộcbody

Thời điểm tạo (ISO 8601).

typestringbắt buộcbody

Kiểu key: ssh hoặc x509.

Mã trạng thái

Thành công

Mã	Mô tả
200 - OK	Request thành công (import có thể trả về 200).
201 - Created	Key pair mới đã được tạo hoặc import.

Lỗi

Mã	Mô tả
400 - Bad Request	Body hoặc tham số không hợp lệ.
401 - Unauthorized	Xác thực thất bại hoặc thiếu.
403 - Forbidden	Policy không cho phép thao tác này.
409 - Conflict	Tên đã tồn tại hoặc xung đột thao tác.

Response mẫu

Key pair được tạo

Response body

{
  "keypair": {
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMII<...>\n-----END RSA PRIVATE KEY-----\n",
    "name": "apikey1",
    "public_key": "ssh-rsa AAAA<...> Generated-by-Nova",
    "fingerprint": "67:c0:a2:8a:b4:c8:50:de:80:91:ed:79:14:17:37:90",
    "created_at": "2025-10-08T08:49:39.071378",
    "user_id": "64166c7effeb4a89b59c073588099640"
  }
}

Public key được import

{
    "keypair": {
        "name": "apikey2",
        "public_key": "ssh-rsa AAAA<...>",
        "fingerprint": "67:c0:a2:8a:b4:c8:50:de:80:91:ed:79:14:17:37:90",
        "created_at": "2025-10-08T08:53:28.769149",
        "user_id": "64166c7effeb4a89b59c073588099640"
    }
}

Lưu ý và best practice

• Luôn lưu private_key trả về một cách an toàn (ví dụ chmod 600). Không thể lấy lại sau đó.
• So sánh fingerprint để kiểm tra tính toàn vẹn của key sau khi upload.
• Đặt tên dễ hiểu; tên này được dùng khi tạo máy ảo (key_name).
• Với Ed25519 hoặc các kiểu key hiện đại khác, kiểm tra deployment có hỗ trợ không, nếu không import có thể trả về 400.
• Chỉ dùng user_id cho các trường hợp admin thật cần thiết; nên audit các thao tác này.

Xem thêm

• Liệt kê SSH key pair