KubernetesGatewayExtensions Methods

AddGateway(IResourceBuilder<KubernetesEnvironmentResource>, string) extension IResourceBuilder<KubernetesGatewayResource>

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.

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

KubernetesGatewayExtensions.cs#L37-L48

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

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"));

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

Adds a Kubernetes metadata annotation to the generated Gateway resource.

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

KubernetesGatewayExtensions.cs

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.

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

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

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

KubernetesGatewayExtensions.cs

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.

WithGatewayClass(IResourceBuilder<KubernetesGatewayResource>, string) extension IResourceBuilder<KubernetesGatewayResource>

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

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

KubernetesGatewayExtensions.cs

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.

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

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

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

KubernetesGatewayExtensions.cs

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.

WithHostname(IResourceBuilder<KubernetesGatewayResource>, string) extension IResourceBuilder<KubernetesGatewayResource>

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.

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

KubernetesGatewayExtensions.cs

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.

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

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

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

KubernetesGatewayExtensions.cs

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.

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

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.

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

KubernetesGatewayExtensions.cs#L104-L119

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 optional The path matching strategy. Defaults to IngressPathType.Prefix.

Returns

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

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

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.

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

KubernetesGatewayExtensions.cs#L141-L157

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 optional The path matching strategy. Defaults to IngressPathType.Prefix.

Returns

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

WithTls(IResourceBuilder<KubernetesGatewayResource>, string) extension IResourceBuilder<KubernetesGatewayResource>

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.

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

KubernetesGatewayExtensions.cs

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.

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

Configures TLS termination using a parameter for the secret name.

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

KubernetesGatewayExtensions.cs

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.

WithTls(IResourceBuilder<KubernetesGatewayResource>) extension IResourceBuilder<KubernetesGatewayResource>

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

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

KubernetesGatewayExtensions.cs#L252-L260

Parameters

builder IResourceBuilder<KubernetesGatewayResource> The gateway resource builder.

Returns

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