# KubernetesGatewayExtensions Methods

- Package: [Aspire.Hosting.Kubernetes](/reference/api/csharp/aspire.hosting.kubernetes.md)
- Type: [KubernetesGatewayExtensions](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesgatewayextensions.md)
- Kind: `Methods`
- Members: `12`

Provides extension methods for configuring Kubernetes Gateway API resources in the Aspire application model.

## AddGateway(IResourceBuilder<KubernetesEnvironmentResource>, string)

- Name: `AddGateway(IResourceBuilder<KubernetesEnvironmentResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs#L37-L48)

Adds a Kubernetes Gateway API Gateway resource to the application model as a child of the specified Kubernetes environment. The gateway generates a `gateway.networking.k8s.io/v1 Gateway` resource and one or more `HTTPRoute` resources in the Helm chart output at publish time.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> AddGateway(
        this IResourceBuilder<KubernetesEnvironmentResource> builder,
        string name)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesEnvironmentResource>`)
  The Kubernetes environment resource builder.
- `name` (`string`)
  The name of the gateway resource.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Examples

```csharp
var k8s = builder.AddKubernetesEnvironment("k8s");
var gateway = k8s.AddGateway("public")
    .WithGatewayClass("azure-alb-external");

var api = builder.AddProject<MyApi>("api");
gateway.WithRoute("/api", api.GetEndpoint("http"));
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithGatewayAnnotation(IResourceBuilder<KubernetesGatewayResource>, string, string)

- Name: `WithGatewayAnnotation(IResourceBuilder<KubernetesGatewayResource>, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Adds a Kubernetes metadata annotation to the generated Gateway resource.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithGatewayAnnotation(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string key,
        string value)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `key` (`string`)
  The annotation key.
- `value` (`string`)
  The annotation value.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Remarks

This sets Kubernetes `metadata.annotations` on the generated K8S Gateway resource, not Aspire `ApplicationModel.IResourceAnnotation` instances. These are key-value string pairs used by ingress controllers for provider-specific configuration.

For Azure Application Gateway for Containers (AGC), you typically need: `alb.networking.azure.io/alb-name` and `alb.networking.azure.io/alb-namespace`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithGatewayAnnotation(IResourceBuilder<KubernetesGatewayResource>, string, IResourceBuilder<ParameterResource>)

- Name: `WithGatewayAnnotation(IResourceBuilder<KubernetesGatewayResource>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Adds a Kubernetes metadata annotation with a parameter value that will be resolved at deploy time.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithGatewayAnnotation(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string key,
        IResourceBuilder<ParameterResource> value)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `key` (`string`)
  The annotation key.
- `value` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the annotation value.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithGatewayClass(IResourceBuilder<KubernetesGatewayResource>, string)

- Name: `WithGatewayClass(IResourceBuilder<KubernetesGatewayResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Sets the GatewayClass name that selects which controller implementation handles this gateway.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithGatewayClass(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string className)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `className` (`string`)
  The GatewayClass name (e.g., `"azure-alb-external"`, `"istio"`).

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithGatewayClass(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)

- Name: `WithGatewayClass(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Sets the GatewayClass name using a parameter that will be resolved at deploy time.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithGatewayClass(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        IResourceBuilder<ParameterResource> className)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `className` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the GatewayClass name.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithHostname(IResourceBuilder<KubernetesGatewayResource>, string)

- Name: `WithHostname(IResourceBuilder<KubernetesGatewayResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Adds a hostname that this gateway's routes match. Multiple hostnames can be added by calling this method repeatedly. Hostnames are used as `hostnames` in generated `HTTPRoute` resources and as HTTPS listener hostnames when TLS is configured.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithHostname(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string hostname)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `hostname` (`string`)
  The hostname to match (e.g., `"api.example.com"`).

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithHostname(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)

- Name: `WithHostname(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Adds a hostname using a parameter that will be resolved at deploy time.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithHostname(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        IResourceBuilder<ParameterResource> hostname)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `hostname` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the hostname value.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithRoute(IResourceBuilder<KubernetesGatewayResource>, string, EndpointReference, IngressPathType)

- Name: `WithRoute(IResourceBuilder<KubernetesGatewayResource>, string, EndpointReference, IngressPathType)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs#L104-L119)

Adds a path-based routing rule to the gateway. The rule matches all hosts and routes traffic matching the specified path to the given endpoint's backing Kubernetes service. This generates an `HTTPRoute` resource attached to the Gateway.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithRoute(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string path,
        EndpointReference endpoint,
        IngressPathType pathType = IngressPathType.Prefix)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `path` (`string`)
  The URL path to match (e.g., `"/"` or `"/api"`). Must start with `/`.
- `endpoint` (`EndpointReference`)
  The endpoint reference identifying the target service and port.
- `pathType` ([IngressPathType](/reference/api/csharp/aspire.hosting.kubernetes/ingresspathtype.md)) `optional`
  The path matching strategy. Defaults to [IngressPathType.Prefix](/reference/api/csharp/aspire.hosting.kubernetes/ingresspathtype/fields.md).

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithRoute(IResourceBuilder<KubernetesGatewayResource>, string, string, EndpointReference, IngressPathType)

- Name: `WithRoute(IResourceBuilder<KubernetesGatewayResource>, string, string, EndpointReference, IngressPathType)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs#L141-L157)

Adds a host-and-path-based routing rule to the gateway. The rule matches traffic for the specified host and path, routing it to the given endpoint's backing Kubernetes service. This generates an `HTTPRoute` resource with a `hostnames` filter.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithRoute(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string host,
        string path,
        EndpointReference endpoint,
        IngressPathType pathType = IngressPathType.Prefix)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `host` (`string`)
  The hostname to match (e.g., `"api.example.com"`).
- `path` (`string`)
  The URL path to match. Must start with `/`.
- `endpoint` (`EndpointReference`)
  The endpoint reference identifying the target service and port.
- `pathType` ([IngressPathType](/reference/api/csharp/aspire.hosting.kubernetes/ingresspathtype.md)) `optional`
  The path matching strategy. Defaults to [IngressPathType.Prefix](/reference/api/csharp/aspire.hosting.kubernetes/ingresspathtype/fields.md).

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithTls(IResourceBuilder<KubernetesGatewayResource>, string)

- Name: `WithTls(IResourceBuilder<KubernetesGatewayResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Configures TLS termination on the gateway by adding an HTTPS listener that references a Kubernetes TLS secret. The Gateway terminates TLS and forwards plain HTTP to backends. This does not create a separate route -- existing HTTPRoutes serve both HTTP and HTTPS. The TLS configuration applies to all hostnames configured via [KubernetesGatewayExtensions.WithHostname(IResourceBuilder<KubernetesGatewayResource>, string)](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesgatewayextensions/methods.md#withhostname-iresourcebuilder-kubernetesgatewayresource-string).

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithTls(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        string secretName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `secretName` (`string`)
  The name of the Kubernetes `kubernetes.io/tls` Secret.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithTls(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)

- Name: `WithTls(IResourceBuilder<KubernetesGatewayResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs)

Configures TLS termination using a parameter for the secret name.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithTls(
        this IResourceBuilder<KubernetesGatewayResource> builder,
        IResourceBuilder<ParameterResource> secretName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.
- `secretName` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the secret name.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

## WithTls(IResourceBuilder<KubernetesGatewayResource>)

- Name: `WithTls(IResourceBuilder<KubernetesGatewayResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesGatewayResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/5bd693ae1897dee5e2ce71c2cc08879c1c7eff51/src/Aspire.Hosting.Kubernetes/KubernetesGatewayExtensions.cs#L252-L260)

Configures TLS termination with an auto-generated secret name derived from the gateway name.

```csharp
public static class KubernetesGatewayExtensions
{
    public static IResourceBuilder<KubernetesGatewayResource> WithTls(
        this IResourceBuilder<KubernetesGatewayResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesGatewayResource>`)
  The gateway resource builder.

## Returns

`IResourceBuilder<KubernetesGatewayResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.