Stage troubleshoot managed instance configuration

Author: Mike Ray (Microsoft)

articles/azure-arc/data/toc.yml

@@ -233,7 +233,11 @@ items:
             - name: Reprovision replica
               href: reprovision-replica.md
         - name: Troubleshoot
-          href: troubleshoot-managed-instance.md
+          items:
+            - name: General
+              href: troubleshoot-managed-instance.md
+            - name: configuration
+              href: troubleshoot-managed-instance-configuration.md
 - name: Azure Arc-enabled PostgreSQL (preview) 
   items:
     - name: Overview

articles/azure-arc/data/troubleshoot-managed-instance-configuration.md

@@ -0,0 +1,75 @@
+---
+title: Troubleshoot configuration - Azure Arc-enabled SQL Managed Instance
+description: Describes how to troubleshoot configuration. Includes steps to provide configuration files for Azure Arc-enabled SQL Managed Instance Azure Arc-enabled data services
+author: MikeRayMSFT
+ms.author: mikeray
+ms.topic: troubleshooting-general 
+ms.date: 04/10/2023
+---
+
+# User-provided configuration files
+
+Arc data services provide management of configuration settings and files in the system. Configuration files such as `mssql.conf`, `mssql.json`, `krb5.conf` are generated by the system using the user-provided settings in the custom resource spec as well as some system-determined settings. The scope of what settings are supported and what changes can be made to the configuration files using the custom resource spec evolves over time. You may need to try changes in the configuration files that are not possible through the settings on the custom resource spec.
+
+To alleviate this problem, Arc data services allow you to to provide configuration file content for a selected set of files through a Kubernetes `ConfigMap`. The information in the `ConfigMap` effectively overrides the file content that the system would have otherwise generated. This allows you to try some scenarios that may not be possible through the spec today.
+
+For Arc SQL Managed Instance, the supported configuration files that can be overridden using this method are:
+- `mssql.conf`
+- `mssql.json`
+- `krb5.conf`
+
+## Steps to provide override configuration files
+
+### 1. Prepare the content of the configuration file
+Prepare the content of the file that you would like to provide an override for.
+
+### 2. Create a `ConfigMap`
+
+Create a `ConfigMap` spec to store the content of the configuration file. The key in the `ConfigMap` dictionary should be the name of the file, and the value should be the content.
+You can provide file overrides for multiple configuration files in one `ConfigMap`.
+The `ConfigMap` must be in the same namespace as the SQL Managed Instance.
+
+The following spec shows an example of how to provide an override for mssql.conf file:
+
+```json
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: sqlmifo-cm
+  namespace: test
+data:
+  mssql.conf: "[language]\r\nlcid = 1033\r\n\r\n[licensing]\r\npid = GeneralPurpose\r\n\r\n[network]\r\nforceencryption = 0\r\ntlscert = /var/run/secrets/managed/certificates/mssql/mssql-certificate.pem\r\ntlsciphers = ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384\r\ntlskey = /var/run/secrets/managed/certificates/mssql/mssql-privatekey.pem\r\ntlsprotocols = 1.2\r\n\r\n[sqlagent]\r\nenabled = False\r\n\r\n[telemetry]\r\ncustomerfeedback = false\r\n\r\n"
+```
+
+Apply the `ConfigMap` in Kubernetes using `kubectl apply -f <filename>`.
+
+### 3. Provide the name of the ConfigMap in SQL Managed Instance spec
+
+In SQL Managed Instance spec, provide the name of the ConfigMap in the field `spec.fileOverrideConfigMap`.
+The SQL Managed Instance `apiVersion` must be at least v12 (released in April 2023).
+
+The following SQL Managed Instance spec shows an example of how to provide the name of the ConfigMap.
+
+```json
+apiVersion: sql.arcdata.microsoft.com/v12
+kind: SqlManagedInstance
+metadata:
+  name: sqlmifo
+  namespace: test
+spec:
+  fileOverrideConfigMap: sqlmifo-cm
+  ...
+```
+
+Apply the SQL Managed Instance spec in Kubernetes. This will lead to the delivery of the provided configuration files to Arc SQL Managed Instance container.
+
+### 4. Check that the files are downloaded in the arc-sqlmi container.
+The locations of supported files in the container are as follows:
+1. mssql.conf: /var/run/config/mssql/mssql.conf
+1. mssql.json: /var/run/config/mssql/mssql.json
+1. krb5.conf: /etc/krb5.conf
+
+
+## Next steps
+
+[Get logs to troubleshoot Azure Arc-enabled data services](troubleshooting-get-logs.md)