Feat: Add documentation for servicediscovery filters (#1142)

* feat: add documentation for servicediscovery filters

* feat: line break code for readability

* docs: add newline for new sentence

* docs: add links to aws docs

* feat: display commands separately

content/en/user-guide/aws/servicediscovery/index.md

@@ -8,19 +8,24 @@ tags: ["Pro image"]
 
 ## Introduction
 
-Service Discovery simplifies the management and discovery of services by locating and connecting to the components and resources that make up their applications. Service Discovery allows for a centralized mechanism for dynamically registering, tracking, and resolving service instances, allowing seamless communication between services. Service discovery uses Cloud Map API actions to manage HTTP and DNS namespaces for services, enabling automatic registration and discovery of services running in the cluster. 
+Service Discovery simplifies the management and discovery of services by locating and connecting to the components and resources that make up their applications.
+Service Discovery allows for a centralized mechanism for dynamically registering, tracking, and resolving service instances, allowing seamless communication between services.
+Service discovery uses Cloud Map API actions to manage HTTP and DNS namespaces for services, enabling automatic registration and discovery of services running in the cluster.
 
-LocalStack allows you to use the Service Discovery APIs in your local environment to monitor and manage your services across various environments and network topologies. The supported APIs are available on our [API coverage page](https://docs.localstack.cloud/references/coverage/coverage_servicediscovery/), which provides information on the extent of Service Discovery's integration with LocalStack.
+LocalStack allows you to use the Service Discovery APIs in your local environment to monitor and manage your services across various environments and network topologies.
+The supported APIs are available on our [API coverage page](https://docs.localstack.cloud/references/coverage/coverage_servicediscovery/), which provides information on the extent of Service Discovery's integration with LocalStack.
 
 ## Getting Started
 
 This guide is designed for users new to Service Discovery and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script.
 
-Start your LocalStack container using your preferred method. We will demonstrate how to create an ECS service containing a Fargate task that uses Service Discovery with the AWS CLI.
+Start your LocalStack container using your preferred method.
+We will demonstrate how to create an ECS service containing a Fargate task that uses Service Discovery with the AWS CLI.
 
 ### Create a Cloud Map service discovery namespace
 
-To set up a private Cloud Map service discovery namespace, you can utilize the [`CreatePrivateDnsNamespace`](https://docs.aws.amazon.com/cloud-map/latest/api/API_CreatePrivateDnsNamespace.html) API. This API allows you to define a custom name for your namespace and specify the VPC ID where your services will be located. Before proceeding, make sure to create the required VPC.
+To set up a private Cloud Map service discovery namespace, you can utilize the [`CreatePrivateDnsNamespace`](https://docs.aws.amazon.com/cloud-map/latest/api/API_CreatePrivateDnsNamespace.html) API.
+This API allows you to define a custom name for your namespace and specify the VPC ID where your services will be locatedBefore proceeding, make sure to create the required VPC.
 
 To create the private Cloud Map service discovery namespace, execute the following command:
 
@@ -30,7 +35,9 @@ $ awslocal servicediscovery create-private-dns-namespace \
       --vpc <vpc-id>
 {{< /command >}}
 
-Ensure that you replace `<vpc-id>` with the actual ID of the VPC you intend to use for the namespace. Upon running this command, you will receive an output containing an `OperationId`. This identifier can be used to check the status of the operation.
+Ensure that you replace `<vpc-id>` with the actual ID of the VPC you intend to use for the namespace.
+Upon running this command, you will receive an output containing an `OperationId`.
+This identifier can be used to check the status of the operation.
 
 To verify the status of the operation, execute the following command:
 
@@ -43,7 +50,8 @@ The output will consist of a `NAMESPACE` ID, which you will need to create a ser
 
 ### Create a Cloud Map service
 
-After creating the private Cloud Map service discovery namespace, you can proceed to create a service within that namespace using the [`CreateService`](https://docs.aws.amazon.com/cloud-map/latest/api/API_CreateService.html) API. This service represents a specific component or resource in your application.
+After creating the private Cloud Map service discovery namespace, you can proceed to create a service within that namespace using the [`CreateService`](https://docs.aws.amazon.com/cloud-map/latest/api/API_CreateService.html) API
+This service represents a specific component or resource in your application.
 
 To create a service within the namespace, execute the following command:
 
@@ -54,13 +62,15 @@ $ awslocal servicediscovery create-service \
       --health-check-custom-config FailureThreshold=1
 {{< /command >}}
 
-Upon successful execution, the output will provide you with the Service ID and the Amazon Resource Name (ARN) of the newly created service. These identifiers will be useful for further operations or integrations.
+Upon successful execution, the output will provide you with the Service ID and the Amazon Resource Name (ARN) of the newly created service.
+These identifiers will be useful for further operations or integrations.
 
 ### Create an ECS cluster
 
 To integrate the service you created earlier with an ECS (Elastic Container Service) service, you can follow the steps below.
 
-Start by creating an ECS cluster using the [`CreateCluster`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCluster.html) API. Execute the following command:
+Start by creating an ECS cluster using the [`CreateCluster`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCluster.html) API.
+Execute the following command:
 
 {{< command >}}
 $ awslocal ecs create-cluster \
@@ -69,7 +79,8 @@ $ awslocal ecs create-cluster \
 
 ### Register a task definition
 
-Next, you will register a task definition that's compatible with Fargate. Create a file named `fargate-task.json` and add the following content:
+Next, you will register a task definition that's compatible with Fargate.
+Create a file named `fargate-task.json` and add the following content:
 
 ```json
 {
@@ -104,7 +115,8 @@ Next, you will register a task definition that's compatible with Fargate. Create
 }
 ```
 
-Register the task definition using the [`RegisterTaskDefinition`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) API. Execute the following command:
+Register the task definition using the [`RegisterTaskDefinition`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) API.
+Execute the following command:
 
 {{< command >}}
 $ awslocal ecs register-task-definition \
@@ -113,13 +125,16 @@ $ awslocal ecs register-task-definition \
 
 ### Create an ECS service
 
-To create an ECS service, you will need to retrieve the `securityGroups` and `subnets` associated with the VPC used to create the Cloud Map namespace. You can obtain this information by using the [`DescribeVpcs`](https://docs.aws.amazon.com/vpc/latest/APIReference/API_DescribeVpcs.html) API. Execute the following command to retrieve the details of all VPCs:
+To create an ECS service, you will need to retrieve the `securityGroups` and `subnets` associated with the VPC used to create the Cloud Map namespace.
+You can obtain this information by using the [`DescribeVpcs`](https://docs.aws.amazon.com/vpc/latest/APIReference/API_DescribeVpcs.html) API.
+Execute the following command to retrieve the details of all VPCs:
 
 {{< command >}}
 $ awslocal ec2 describe-vpcs
 {{< /command >}}
 
-The output will include a list of VPCs. Locate the VPC that was used to create the Cloud Map namespace and make a note of its `VpcId` value.
+The output will include a list of VPCs.
+Locate the VPC that was used to create the Cloud Map namespace and make a note of its `VpcId` value.
 
 Next, execute the following commands to retrieve the `securityGroups` and `subnets` associated with the VPC:
 
@@ -129,7 +144,8 @@ $ awslocal ec2 describe-security-groups --filters Name=vpc-id,Values=vpc-<ID> --
 $ awslocal ec2 describe-subnets --filters Name=vpc-id,Values=vpc-<ID> --query 'Subnets[*].[SubnetId, CidrBlock]' --output text
 {{< /command >}}
 
-Replace `<VpcId>` with the actual VpcId value of the VPC you identified earlier. Make a note of the `GroupId` and `SubnetId` values.
+Replace `<VpcId>` with the actual VpcId value of the VPC you identified earlier.
+Make a note of the `GroupId` and `SubnetId` values.
 
 Create a new file named `ecs-service-discovery.json` and add the following content to it:
 
@@ -156,7 +172,8 @@ Create a new file named `ecs-service-discovery.json` and add the following conte
 }
 ```
 
-Create your ECS service using the [`CreateService`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) API. Execute the following command:
+Create your ECS service using the [`CreateService`](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) API.
+Execute the following command:
 
 {{< command >}}
 $ awslocal ecs create-service \
@@ -165,13 +182,58 @@ $ awslocal ecs create-service \
 
 ### Verify the service
 
-You can use the Service Discovery service ID to verify that the service was created successfully. Execute the following command:
+You can use the Service Discovery service ID to verify that the service was created successfully.
+Execute the following command:
 
 {{< command >}}
 $ awslocal servicediscovery list-instances \
        --service-id <service-id>
 {{< /command >}}
 
-The output will consist of the resource ID, and you can further use the [`DiscoverInstances`](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) API. This API allows you to query the DNS records associated with the service and perform various operations.
+The output will consist of the resource ID, and you can further use the [`DiscoverInstances`](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) API.
+This API allows you to query the DNS records associated with the service and perform various operations.
 
 To explore the DNS records of your service and perform other operations, refer to the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/index.html) for comprehensive instructions and examples.
+
+### Using filters
+Filters can be used to narrow down the results of a list operation.
+Filters are supported for the following operations:
+
+- [`list-namespaces`](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/list-namespaces.html)
+- [`list-services`](https://docs.aws.amazon.com/cli/latest/reference/ecs/list-services.html)
+- [`discover-instances`](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/discover-instances.html)
+
+Using `list-namespaces` you can filter for the parameters `TYPE`, `NAME`, `HTTP_NAME`.
+Using `list-services` it is only possible to filter for `NAMESPACE_ID`.
+Both `list-services` and `list-namespaces` support `EQ` (default condition if not specified) and `BEGINS_WITH` as conditions.
+Both conditions and only support a single value to match by.
+The following examples demonstrate how to use filters with these operations:
+
+{{< command >}}
+$ awslocal servicediscovery list-namespaces \
+    --filters "Name=HTTP_NAME,Values=['example-namespace'],Condition=EQ"
+{{< /command >}}
+
+{{< command >}}
+$ awslocal servicediscovery list-services \
+    --filters "Name=NAMESPACE_ID,Values=['id_to_match']"
+{{< /command >}}
+
+The command `discover-instance` supports parameters and optional parameters as filter criteria.
+Conditions in parameters must match return values, while if one ore more conditions in optional parameters match, the subset is returned, if no conditions in optional parameters match, all unfiltered results are returned.
+
+This command will only return instances where the parameter `env` is equal to `fuu`:
+{{< command >}}
+$ awslocal servicediscovery discover-instances \
+    --namespace-name example-namespace \
+    --service-name example-service \
+    --query-parameters "env"="fuu"
+{{< /command >}}
+
+This command instead will return all instances where the optional parameter `env` is equal to `bar`, but if no instances match, all instances are returned:
+{{< command >}}
+$ awslocal servicediscovery discover-instances \
+    --namespace-name example-namespace \
+    --service-name example-service \
+    --optional-parameters "env"="bar"
+{{< /command >}}