Make Custom Metrics Basic Authentication Optional

docs/defining-a-custom-metric-87e657e.md

@@ -12,7 +12,7 @@ Define your own metrics to scale applications based on your requirements.
 
 As an alternative to the standard metrics provided by the Application Autoscaler, you can also define custom metrics such as memory consumed in megabytes or in percentage, response time, and throughput for scaling. Custom metrics offer more flexibility, so that you can scale applications based on your own requirements.
 
-To use custom metrics, you need to perform the following tasks:
+To use custom metrics, your application needs to perform the following tasks:
 
 1.  Report a custom metric to the Application Autoscaler by defining a policy.
 
@@ -35,24 +35,67 @@ The following example shows a policy with a custom metric:
          "adjustment":"+1"
       }
    ]
+}
 
 ```
 
-> ### Note:  
+> ### Note:
 > The metric type used for custom metrics must not be any of the standard metric types.
 
-> ### Tip:  
+> ### Tip:
 > We recommend a minimum duration of one minute between successive emissions of a custom metric.
 
+As part of the binding process, the Application Autoscaler service instance provides necessary credentials to emit custom metrics. The generation of these credentials is based on the credential type parameter in the service binding. The supported credential types are `binding-secret` and `x509`. If no credential type is provided, `binding-secret` is used as the default credential type.
+
 
 
 ## Procedure
 
 1.  Bind your application with the Application Autoscaler service instance using a policy that contains custom metrics scaling rule.
 
+     ```
+     # sample policy.json with credential Type as x509
+    {
+        "instance_min_count":1,
+        "instance_max_count":4,
+        "scaling_rules":[
+            {
+            "metric_type":"jobqueue",
+            "breach_duration_secs":60,
+            "threshold":100,
+            "operator":">=",
+            "cool_down_secs":120,
+            "adjustment":"+1"
+            }
+        ],
+        "credential-type": "x509"
+    }
+
+    # bind the service instance with the scaling policy
+    cf bind-service <application> <application-autoscaler-service-instance> -c policy.json
+    ```
+
 2.  Read custom metrics binding credentials from the application environment.
 
-    > ### Sample Code:  
+    > ###  Binding Credentials for mTLS
+    > ```
+    > "custom_metrics": {
+    >       "mtls_url": "https://autoscaler-metrics-mtls.cf.<landscape>.hana.ondemand.com",
+    >      }
+    > ```
+
+3.  **Authenticate with X.509 Certificate**: Your application requires base url, certificate and a private key for mutual TLS authentication \(mTLS\).
+
+    - use the base URL provided in the `mtls_url` of the service binding
+    - use the X.509 certificate and private key from the paths provided in the environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY` respectively.
+
+    >       ### Notes:
+             The environment variables `CF_INSTANCE_CERT` and `CF_INSTANCE_KEY` are not shown in the cockpit or using the `cf env` command. They are only visible inside the running application container.
+    >       The X.509 certificate and private key pair are valid for 24 hours. At least 20 minutes before expiration, they are regenerated and new files replace the existing files. Make sure that your code reloads the X.509 certificate and private key pair if they are expired. See [Using Instance Identity Credentials](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) in the Cloud Foundry Documentation.
+
+    **Authenticate with Basic Authentication (Deprecated, do not use)**: `url`, `username`, and `password` in the application environment are provided for backwards compatibility with the HTTP basic authentication scheme and should not be used going forward. If your application still needs to authenticate with basic authentication, use credential-type `binding-secret` in the service binding and plan to migrate to mTLS (`x509`) authentication until 2025-01-23.
+
+    > ####  Binding Credentials for Basic Authentication
     > ```
     > "custom_metrics": {
     >       "mtls_url": "https://autoscaler-metrics-mtls.cf.<landscape>.hana.ondemand.com",
@@ -63,13 +106,6 @@ The following example shows a policy with a custom metric:
     > 
     > ```
 
-3.  Use the X.509 certificate in the file with the path provided in the environment variable `CF_INSTANCE_CERT`, and the private key in the file with the path provided in the environment variable `CF_INSTANCE_KEY` as certificate and key for mutual TLS authentication \(mTLS\) with the base URL provided in the `mtls_url` of the service binding.
-
-    > ### Note:  
-    > The X.509 certificate and private key pair are valid for 24 hours. At least 20 minutes before expiration, they are regenerated and new files replace the existing files. Make sure that your code reloads the X.509 certificate and private key pair if they are expired. See [Using Instance Identity Credentials](https://docs.cloudfoundry.org/devguide/deploy-apps/instance-identity.html) in the Cloud Foundry Documentation.
-
-    `url`, `username`, and `password` are provided for backwards compatibility with the HTTP basic authentication scheme and should not be used going forward.
-
 4.  Push custom metrics at an interval of your choice using APIs. For the REST API specification, see [Application Autoscaler custom metrics API](https://api.sap.com/api/ApplicationAutoscalerCustomMetricsAPI/resource).