Zum Hauptinhalt springen

Get an Ingress

GET/v2/ingresses/{ingressId}
API-Version
v2
Request-Methode
GET
Operation-ID
ingress-get-ingress

Request​

  • ingressIdstring (uuid)required

    ID of the Ingress to be retrieved.

Responses​

Format
application/json
Beschreibung

OK

  • accessProtectionobject

    Login protection of an Ingress: one identity provider for the hostname, enabled and configured per path.

    • allPathsobject

      Protects every path of the Ingress, also those added later; redirects stay reachable.

      • passIdentityHeadersbooleanrequired

        Whether the targets receive the identity of the logged-in user as request headers.

      • rulesobjectrequired

        Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.

        • allowAnyAuthenticatedUserbooleanrequired

          Every user the provider authenticates may pass. Only with the OIDC provider.

        • allowedEmailDomainsArray von string (idn-hostname)required
          • Array[
            • *string (idn-hostname)
            ]
        • allowedEmailsArray von string (email)required
          • Array[
            • *string (email)
            ]
        • projectMembersOnlybooleanrequired

          Only members of the Ingress's Project may pass. Requires the mStudio provider.

    • pathsArray von objectrequired

      The protected paths. Paths not listed here are not protected, even if a parent path is. Empty if allPaths is set.

      • Array[
        • *object
          • passIdentityHeadersbooleanrequired

            Whether the target receives the identity of the logged-in user as request headers.

          • pathstringrequired
          • rulesobjectrequired

            Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.

            • allowAnyAuthenticatedUserbooleanrequired

              Every user the provider authenticates may pass. Only with the OIDC provider.

            • allowedEmailDomainsArray von string (idn-hostname)required
              • Array[
                • *string (idn-hostname)
                ]
            • allowedEmailsArray von string (email)required
              • Array[
                • *string (email)
                ]
            • projectMembersOnlybooleanrequired

              Only members of the Ingress's Project may pass. Requires the mStudio provider.

        ]
    • providereine von 2 Alternativenrequired
      • Alternativeobject

        Users log in with their mStudio account.

        • mstudioobjectrequired
      • Alternativeobject

        Users log in with an external OpenID Connect provider. The client secret is never returned.

        • oidcobjectrequired
          • clientIdstringrequired
          • issuerUrlstring (uri)required
  • dnsValidationErrorsArray von string (einer von: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)required

    A list of errors that occurred while validating the ingress's dns before requesting a certificate. ERROR_QUAD_A and ERROR_NO_A_RECORD are deprecated and no longer reported.

    • Array[
      • *string (einer von: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)
      ]
  • hostnamestring (idn-hostname)required
  • idstring (uuid)required
  • ipsobjectrequired
    • v4Array von string (ipv4)required
      • Array[
        • *string (ipv4)
        ]
    • v6Array von string (ipv6)required
      • Array[
        • *string (ipv6)
        ]
  • isDefaultbooleanrequired

    Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.

  • isDomainboolean
  • isEnabledbooleanrequired
  • ownershipobjectrequired
    • txtRecordstring
    • verifiedbooleanrequired

      Whether the domain ownership is verified or not.

  • pathsArray von objectrequired

    A list of paths. The default path / is always present and cannot be removed.

    • Array[
      • *object
        • pathstringrequired
        • targeteine von 4 Alternativenrequired
          • Alternativeobject

            Redirect requests to this path to another URL

            • urlstring (uri)required

              The URL to which requests should be forwarded.

          • Alternativeobject

            Serve a specific app installation

            • installationIdstring (uuid)required

              The ID of an app installation within the same project to which requests should be forwarded.

          • Alternativeobject

            Serve a generic default page

            • useDefaultPagebooleanrequired

              Set this to true to serve a generic default site at this path.

          • Alternativeobject

            Forward requests to this path to a specific container.

            • containerobjectrequired
              • idstring (uuid)required
              • portProtocolstring (docker-network-port)required

                docker-compose port specification in format port/protocol (e.g. 8080/TCP)

      ]
  • projectIdstring (uuid)required
  • senderLoginProtectionboolean

    If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.

  • tlseine von 2 Alternativenrequired
    • Alternativeobject
      • acmebooleanrequired

        Has to be true, as ssl cannot be deactivated.

      • isCreatedbooleanrequired
      • requestDeadlinestring (date-time)
    • Alternativeobject
      • certificateIdstring (uuid)required
Content-Type: application/json

{
  "accessProtection": {
    "allPaths": {
      "passIdentityHeaders": true,
      "rules": {
        "allowAnyAuthenticatedUser": true,
        "allowedEmailDomains": [
          "example.com"
        ],
        "allowedEmails": [
          "ada@example.com"
        ],
        "projectMembersOnly": true
      }
    },
    "paths": [
      {
        "passIdentityHeaders": true,
        "path": "/admin",
        "rules": {
          "allowAnyAuthenticatedUser": true,
          "allowedEmailDomains": [
            "example.com"
          ],
          "allowedEmails": [
            "ada@example.com"
          ],
          "projectMembersOnly": true
        }
      }
    ],
    "provider": {
      "mstudio": {}
    }
  },
  "dnsValidationErrors": [
    "ERROR_UNSPECIFIED"
  ],
  "hostname": "some-hostname.example",
  "id": "f0f86186-0a5a-45b2-aa33-502777496347",
  "ips": {
    "v4": [
      "string"
    ],
    "v6": [
      "string"
    ]
  },
  "isDefault": true,
  "isDomain": true,
  "isEnabled": true,
  "ownership": {
    "txtRecord": "string",
    "verified": true
  },
  "paths": [
    {
      "path": "string",
      "target": {
        "url": "https://redirect-target.example"
      }
    }
  ],
  "projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
  "senderLoginProtection": true,
  "tls": {
    "acme": true,
    "isCreated": true,
    "requestDeadline": "1985-10-26T01:21:00.000Z"
  }
}
{
  "properties": {
    "accessProtection": {
      "additionalProperties": false,
      "description": "Login protection of an Ingress: one identity provider for the hostname, enabled and configured per path.",
      "properties": {
        "allPaths": {
          "additionalProperties": false,
          "description": "Protects every path of the Ingress, also those added later; redirects stay reachable.",
          "properties": {
            "passIdentityHeaders": {
              "description": "Whether the targets receive the identity of the logged-in user as request headers.",
              "type": "boolean"
            },
            "rules": {
              "additionalProperties": false,
              "description": "Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.",
              "properties": {
                "allowAnyAuthenticatedUser": {
                  "description": "Every user the provider authenticates may pass. Only with the OIDC provider.",
                  "type": "boolean"
                },
                "allowedEmailDomains": {
                  "items": {
                    "example": "example.com",
                    "format": "idn-hostname",
                    "type": "string"
                  },
                  "type": "array"
                },
                "allowedEmails": {
                  "items": {
                    "example": "ada@example.com",
                    "format": "email",
                    "type": "string"
                  },
                  "type": "array"
                },
                "projectMembersOnly": {
                  "description": "Only members of the Ingress's Project may pass. Requires the mStudio provider.",
                  "type": "boolean"
                }
              },
              "required": [
                "projectMembersOnly",
                "allowedEmails",
                "allowedEmailDomains",
                "allowAnyAuthenticatedUser"
              ],
              "type": "object"
            }
          },
          "required": [
            "rules",
            "passIdentityHeaders"
          ],
          "type": "object"
        },
        "paths": {
          "description": "The protected paths. Paths not listed here are not protected, even if a parent path is. Empty if `allPaths` is set.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "passIdentityHeaders": {
                "description": "Whether the target receives the identity of the logged-in user as request headers.",
                "type": "boolean"
              },
              "path": {
                "example": "/admin",
                "type": "string"
              },
              "rules": {
                "additionalProperties": false,
                "description": "Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.",
                "properties": {
                  "allowAnyAuthenticatedUser": {
                    "description": "Every user the provider authenticates may pass. Only with the OIDC provider.",
                    "type": "boolean"
                  },
                  "allowedEmailDomains": {
                    "items": {
                      "example": "example.com",
                      "format": "idn-hostname",
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "allowedEmails": {
                    "items": {
                      "example": "ada@example.com",
                      "format": "email",
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "projectMembersOnly": {
                    "description": "Only members of the Ingress's Project may pass. Requires the mStudio provider.",
                    "type": "boolean"
                  }
                },
                "required": [
                  "projectMembersOnly",
                  "allowedEmails",
                  "allowedEmailDomains",
                  "allowAnyAuthenticatedUser"
                ],
                "type": "object"
              }
            },
            "required": [
              "path",
              "rules",
              "passIdentityHeaders"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "provider": {
          "oneOf": [
            {
              "additionalProperties": false,
              "description": "Users log in with their mStudio account.",
              "properties": {
                "mstudio": {
                  "additionalProperties": false,
                  "type": "object"
                }
              },
              "required": [
                "mstudio"
              ],
              "type": "object"
            },
            {
              "additionalProperties": false,
              "description": "Users log in with an external OpenID Connect provider. The client secret is never returned.",
              "properties": {
                "oidc": {
                  "additionalProperties": false,
                  "properties": {
                    "clientId": {
                      "type": "string"
                    },
                    "issuerUrl": {
                      "example": "https://idp.example.com",
                      "format": "uri",
                      "type": "string"
                    }
                  },
                  "required": [
                    "issuerUrl",
                    "clientId"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "oidc"
              ],
              "type": "object"
            }
          ]
        }
      },
      "required": [
        "provider",
        "paths"
      ],
      "type": "object"
    },
    "dnsValidationErrors": {
      "description": "A list of errors that occurred while validating the ingress's dns before requesting a certificate. `ERROR_QUAD_A` and `ERROR_NO_A_RECORD` are deprecated and no longer reported.",
      "items": {
        "enum": [
          "ERROR_UNSPECIFIED",
          "ERROR_QUAD_A",
          "ERROR_NO_A_RECORD",
          "ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "hostname": {
      "format": "idn-hostname",
      "type": "string"
    },
    "id": {
      "format": "uuid",
      "type": "string"
    },
    "ips": {
      "properties": {
        "v4": {
          "items": {
            "format": "ipv4",
            "type": "string"
          },
          "type": "array"
        },
        "v6": {
          "items": {
            "format": "ipv6",
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "v4",
        "v6"
      ],
      "type": "object"
    },
    "isDefault": {
      "description": "Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.",
      "type": "boolean"
    },
    "isDomain": {
      "type": "boolean"
    },
    "isEnabled": {
      "type": "boolean"
    },
    "ownership": {
      "properties": {
        "txtRecord": {
          "type": "string"
        },
        "verified": {
          "description": "Whether the domain ownership is verified or not.",
          "type": "boolean"
        }
      },
      "required": [
        "verified"
      ],
      "type": "object"
    },
    "paths": {
      "description": "A list of paths. The default path `/` is always present and cannot be removed.",
      "items": {
        "properties": {
          "path": {
            "type": "string"
          },
          "target": {
            "oneOf": [
              {
                "properties": {
                  "url": {
                    "format": "uri",
                    "type": "string",
                    "description": "The URL to which requests should be forwarded.",
                    "example": "https://redirect-target.example"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object",
                "description": "Redirect requests to this path to another URL"
              },
              {
                "properties": {
                  "installationId": {
                    "format": "uuid",
                    "type": "string",
                    "description": "The ID of an app installation within the same project to which requests should be forwarded."
                  }
                },
                "required": [
                  "installationId"
                ],
                "type": "object",
                "description": "Serve a specific app installation"
              },
              {
                "properties": {
                  "useDefaultPage": {
                    "type": "boolean",
                    "description": "Set this to `true` to serve a generic default site at this path."
                  }
                },
                "required": [
                  "useDefaultPage"
                ],
                "type": "object",
                "description": "Serve a generic default page"
              },
              {
                "properties": {
                  "container": {
                    "properties": {
                      "id": {
                        "format": "uuid",
                        "type": "string"
                      },
                      "portProtocol": {
                        "description": "docker-compose port specification in format port/protocol (e.g. 8080/TCP)",
                        "format": "docker-network-port",
                        "type": "string",
                        "example": "80/tcp"
                      }
                    },
                    "required": [
                      "id",
                      "portProtocol"
                    ],
                    "type": "object",
                    "descriptions": "References a specific port/container combination within the same project."
                  }
                },
                "required": [
                  "container"
                ],
                "type": "object",
                "description": "Forward requests to this path to a specific container."
              }
            ]
          }
        },
        "required": [
          "path",
          "target"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "projectId": {
      "format": "uuid",
      "type": "string"
    },
    "senderLoginProtection": {
      "description": "If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.",
      "type": "boolean"
    },
    "tls": {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "acme": {
              "description": "Has to be `true`, as ssl cannot be deactivated.",
              "type": "boolean"
            },
            "isCreated": {
              "type": "boolean"
            },
            "requestDeadline": {
              "format": "date-time",
              "type": "string"
            }
          },
          "required": [
            "acme",
            "isCreated"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "certificateId": {
              "format": "uuid",
              "type": "string"
            }
          },
          "required": [
            "certificateId"
          ],
          "type": "object"
        }
      ]
    }
  },
  "required": [
    "id",
    "hostname",
    "projectId",
    "isDefault",
    "tls",
    "paths",
    "isEnabled",
    "ips",
    "dnsValidationErrors",
    "ownership"
  ],
  "type": "object"
}

Nutzungsbeispiele​

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/ingresses/f0f86186-0a5a-45b2-aa33-502777496347
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.domain.ingressGetIngress({
  "ingressId": "f0f86186-0a5a-45b2-aa33-502777496347"
});

assertStatus(response, 200);
  
use \Mittwald\ApiClient\Generated\V2\Clients\Domain\IngressGetIngress\IngressGetIngressRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new IngressGetIngressRequest(
  ingressId: "f0f86186-0a5a-45b2-aa33-502777496347"
));
$response = $client->domain()->ingressGetIngress($request);

var_dump($response->getBody();

Auf dieser Seite