Complete preliminary ssh host group feature

2026-10-10 04:28:33 +00:00 · 2025-04-30 18:14:31 -07:00
parent b06eeb0d40
commit b21b0b340b
46 changed files with 561 additions and 94 deletions
@@ -0,0 +1,4 @@
+---
+title: "Add Host"
+openapi: "POST /api/v1/ssh/host-groups/{sshHostGroupId}/hosts"
+---
@@ -0,0 +1,4 @@
+---
+title: "Create"
+openapi: "POST /api/v1/ssh/host-groups"
+---
@@ -0,0 +1,4 @@
+---
+title: "Delete"
+openapi: "DELETE /api/v1/ssh/host-groups/{sshHostGroupId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "List Hosts"
+openapi: "GET /api/v1/ssh/host-groups/{sshHostGroupId}/hosts"
+---
@@ -0,0 +1,4 @@
+---
+title: "List"
+openapi: "GET /api/v2/workspace/{projectId}/ssh-host-groups"
+---
@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/ssh/host-groups/{sshHostGroupId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "Remove Host"
+openapi: "DELETE /api/v1/ssh/host-groups/{sshHostGroupId}/hosts/{sshHostId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "Update"
+openapi: "PATCH /api/v1/ssh/host-groups/{sshHostGroupId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "Create"
+openapi: "POST /api/v1/ssh/hosts"
+---
@@ -0,0 +1,4 @@
+---
+title: "Delete"
+openapi: "DELETE /api/v1/ssh/hosts/{sshHostId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "Issue Host Certificate"
+openapi: "POST /api/v1/ssh/hosts/{sshHostId}/issue-host-cert"
+---
@@ -0,0 +1,4 @@
+---
+title: "Issue User Certificate"
+openapi: "POST /api/v1/ssh/hosts/{sshHostId}/issue-user-cert"
+---
@@ -0,0 +1,4 @@
+---
+title: "List My Hosts"
+openapi: "GET /api/v1/ssh/hosts/"
+---
@@ -0,0 +1,4 @@
+---
+title: "List"
+openapi: "GET /api/v2/workspace/{projectId}/ssh-hosts"
+---
@@ -0,0 +1,4 @@
+---
+title: "Read Host CA Public Key"
+openapi: "GET /api/v1/ssh/hosts/{sshHostId}/host-ca-public-key"
+---
@@ -0,0 +1,4 @@
+---
+title: "Read User CA Public Key"
+openapi: "GET /api/v1/ssh/hosts/{sshHostId}/user-ca-public-key"
+---
@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/ssh/hosts/{sshHostId}"
+---
@@ -0,0 +1,4 @@
+---
+title: "Update"
+openapi: "PATCH /api/v1/ssh/hosts/{sshHostId}"
+---
@@ -0,0 +1,56 @@
+---
+title: "Infisical SSH"
+sidebarTitle: "Host Groups"
+description: "Learn how to organize SSH hosts into groups and manage access policies at scale."
+---
+
+## Concept
+
+Infisical SSH lets you configure host groups to organize and manage multiple SSH hosts with shared access configuration.
+These host groups can be created based on environments (`development`, `staging`, `production`), geographical regions (`us-east`, `eu-west`, `ap-northeast`), or functions (`web-servers`, `database-servers`, `worker-nodes`) to streamline access management across your infrastructure.
+
+Using a host group, you can define login mappings at the group level and have them be applied to all hosts assigned to that group. For example, you can specify that `[email protected]` can login as `ubuntu` on all hosts assigned to the `production` host group.
+
+## Workflow
+
+The typical workflow for using Infisical SSH with host groups consists of the following steps:
+
+1. The administrator creates host groups based on logical groupings (environments, regions, functions, etc.).
+2. The administrator configures login mappings at the host group level to define access policies.
+3. The administrator registers remote hosts with Infisical using the Infisical CLI via the `infisical ssh add-host` command and assigns them to appropriate host groups either using the `--host-group` flag or by adding them to the host group via UI.
+4. User(s) access the remote hosts using the Infisical CLI via the `infisical ssh connect` command, with access determined by the login mappings defined at both host and host group levels.
+
+## Admin Guide for Configuring Host Groups
+
+In the following steps, we'll walk through how to create and configure Host Groups in Infisical SSH, and how to add hosts to these groups.
+
+<Steps>
+  <Step title="Create a host group">
+    1.1. Navigate to your Infisical SSH project and select the **Hosts** tab.
+    
+    1.2. Click **Add Group** in the **Host Groups** section to create a new group.
+    
+    Enter a name (e.g., `production-servers` or `tokyo-region`) and login mapping(s) for the host group.
+    
+    A login mapping for a host group applies to all hosts assigned to the group and dictates what user(s) will be allowed access to the remote hosts
+    in that group under specific login user(s); in the allowed principals, you should select user(s) part of the Infisical SSH project that will
+    be allowed to login to the remote host as the login user.
+    
+    For instance, if you add a mapping to a host group with the login user `ec2-user` to some users John and Alice in Infisical, then they will be allowed to login to any remote host that is part of the group as `ec2-user` which is a system user that
+    exists on the remote host(s).
+    
+    ![ssh group add group](/images/platform/ssh/v2/ssh-group-add-group-1.png)
+    ![ssh group add group 2](/images/platform/ssh/v2/ssh-group-add-group-2.png)
+
+    1.3. Click **Add** to create the host group.
+
+  </Step>
+  
+  <Step title="Add host(s) to the host group">
+    After creating the host group, you can assign a host to it from inside the host group page in the **SSH Hosts** section. Generally, this is where you'll manage the hosts in a group.
+
+    ![ssh group add group - add host](/images/platform/ssh/v2/ssh-group-add-host-1.png)
+    ![ssh group add group - added host](/images/platform/ssh/v2/ssh-group-add-host-2.png)
+
+  </Step>
+</Steps>
@@ -1,6 +1,6 @@
 ---
 title: "Infisical SSH"
-sidebarTitle: "Infisical SSH"
+sidebarTitle: "Overview"
 description: "Learn how to securely provision user SSH access to your infrastructure using SSH certificates."
 ---

@@ -118,7 +118,13 @@
            "documentation/platform/pki/alerting"
          ]
        },
-        "documentation/platform/ssh",
+        {
+          "group": "Infisical SSH",
+          "pages": [
+            "documentation/platform/ssh/overview",
+            "documentation/platform/ssh/host-groups"
+          ]
+        },
        {
          "group": "Key Management (KMS)",
          "pages": [
@@ -887,8 +893,8 @@
              ]
            },
            {
-            "group": "LDAP Password",
-            "pages": [
+              "group": "LDAP Password",
+              "pages": [
                "api-reference/endpoints/secret-rotations/ldap-password/create",
                "api-reference/endpoints/secret-rotations/ldap-password/delete",
                "api-reference/endpoints/secret-rotations/ldap-password/get-by-id",
@@ -1414,6 +1420,34 @@
    {
      "group": "Infisical SSH",
      "pages": [
+        {
+          "group": "Hosts",
+          "pages": [
+            "api-reference/endpoints/ssh/hosts/list-my",
+            "api-reference/endpoints/ssh/hosts/list",
+            "api-reference/endpoints/ssh/hosts/create",
+            "api-reference/endpoints/ssh/hosts/read",
+            "api-reference/endpoints/ssh/hosts/update",
+            "api-reference/endpoints/ssh/hosts/delete",
+            "api-reference/endpoints/ssh/hosts/issue-host-cert",
+            "api-reference/endpoints/ssh/hosts/issue-user-cert",
+            "api-reference/endpoints/ssh/hosts/read-user-ca-pk",
+            "api-reference/endpoints/ssh/hosts/read-host-ca-pk"
+          ]
+        },
+        {
+          "group": "Host Groups",
+          "pages": [
+            "api-reference/endpoints/ssh/groups/list",
+            "api-reference/endpoints/ssh/groups/create",
+            "api-reference/endpoints/ssh/groups/read",
+            "api-reference/endpoints/ssh/groups/update",
+            "api-reference/endpoints/ssh/groups/delete",
+            "api-reference/endpoints/ssh/groups/add-host",
+            "api-reference/endpoints/ssh/groups/list-hosts",
+            "api-reference/endpoints/ssh/groups/remove-host"
+          ]
+        },
        {
          "group": "Certificates",
          "pages": [