KubernetesGatewayExtensions Methods

AddGateway(IResourceBuilder<KubernetesEnvironmentResource>, string)extensionIResourceBuilder<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#L38-L49

Parameters

builderIResourceBuilder<KubernetesEnvironmentResource>The Kubernetes environment resource builder.

namestringThe 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)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

keystringThe annotation key.

valuestringThe 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>)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

keystringThe annotation key.

valueIResourceBuilder<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)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

classNamestringThe 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>)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

classNameIResourceBuilder<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)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

hostnamestringThe 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>)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

hostnameIResourceBuilder<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, GatewayPathMatchType)extensionIResourceBuilder<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,
        GatewayPathMatchType pathType = GatewayPathMatchType.PathPrefix)
    {
        // ...
    }
}

KubernetesGatewayExtensions.cs#L108-L123

Parameters

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

pathstringThe URL path to match (e.g., "/" or "/api"). Must start with /.

endpointEndpointReferenceThe endpoint reference identifying the target service and port.

pathTypeGatewayPathMatchTypeoptionalThe path matching strategy. Defaults to GatewayPathMatchType.PathPrefix.

Returns

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

WithRoute(IResourceBuilder<KubernetesGatewayResource>, string, string, EndpointReference, GatewayPathMatchType)extensionIResourceBuilder<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,
        GatewayPathMatchType pathType = GatewayPathMatchType.PathPrefix)
    {
        // ...
    }
}

KubernetesGatewayExtensions.cs#L146-L162

Parameters

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

hoststringThe hostname to match (e.g., "api.example.com").

pathstringThe URL path to match. Must start with /.

endpointEndpointReferenceThe endpoint reference identifying the target service and port.

pathTypeGatewayPathMatchTypeoptionalThe path matching strategy. Defaults to GatewayPathMatchType.PathPrefix.

Returns

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

WithTls(IResourceBuilder<KubernetesGatewayResource>, string)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

secretNamestringThe 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>)extensionIResourceBuilder<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

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

secretNameIResourceBuilder<ParameterResource>A parameter resource builder for the secret name.

Returns

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

WithTls(IResourceBuilder<KubernetesGatewayResource>)extensionIResourceBuilder<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#L261-L268

Parameters

builderIResourceBuilder<KubernetesGatewayResource>The gateway resource builder.

Returns

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