PD-1583 / 25.04 / Pd 1583 address ix apps and ix applications datasets

content/SCALE/SCALEUIReference/Datasets/_index.md

@@ -192,7 +192,7 @@ Click to show a selectable checklist of **Permissions Advanced** and **Flags Adv
 
 {{< trueimage src="/images/SCALE/Datasets/PermissionsWidgetOwnerNSFv4Options.png" alt="Permissions Widget Owner NFSv4 Options" id="Permissions Widget Owner NFSv4 Options" >}}
 
-A dataset with a POSIX ACL type, such as the ix-applications dataset, is only editable using the **Edit** button.
+A dataset with a POSIX ACL type is only editable using the **Edit** button.
 
 **Edit** opens the [**Edit ACL**]({{< relref "EditACLScreens.md" >}}) for ACL type.
 {{< /expand >}}
@@ -275,7 +275,7 @@ The common settings are **Parent Path**, **Name**, and the **Dataset Preset** (p
 |---------|-------------|
 | **Parent path** | Read-only field that displays the dataset path. Populated with the parent dataset path, adds the name given to the dataset after entering it in **Name**. For example, *tank/shares/smbshare1*. |
 | **Name** | Enter a unique identifier for the dataset. Names allow upper and lower case letters, numbers, and the dash (-) or underscore (_) special characters, but TrueNAS does not allow trailing spaces after the dataset name. You cannot change the dataset name after clicking **Save**. The **Name** field on the **Edit Dataset** screen shows the path. |
-| **Dataset Preset** | Select the option from the dropdown list to define the type of data sharing the dataset uses. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are: <br><li>**Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.<br><li>**SMB** - Select to optimize the dataset for SMB shares. Displays the **Create SMB Share** option pre-selected and **SMB Name** field populated with the value entered in **Name**. Sets the ACL to NFSv4. <br><li> **Apps** - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the **ix-applications** dataset but this is not used for application data storage. <br><li>**Multiprotocol** - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. Allows clients to use either protocol to access the same data. Displays the **Create NFS Share** and **Create SMB Share** options pre-selected and the **SMB Name** field populated with the value entered in **Name**. See [Multiprotcol Shares]({{< relref "MixedModeShares.md" >}}) for more information. Sets the ACL to NFSv4.<br></li>Setting cannot be edited after saving the dataset. |
+| **Dataset Preset** | Select the option from the dropdown list to define the type of data sharing the dataset uses. The options optimize the dataset for a sharing protocol or app and set the ACL type best suited to the dataset purpose. Options are: <br><li>**Generic** - Select for general storage datasets that are not associated with SMB shares, or apps. Sets the ACL to POSIX.<br><li>**SMB** - Select to optimize the dataset for SMB shares. Displays the **Create SMB Share** option pre-selected and **SMB Name** field populated with the value entered in **Name**. Sets the ACL to NFSv4. <br><li> **Apps** - Select to optimize the dataset for use by any application. Sets the ACL to NFSv4. If you plan to deploy container applications, the system automatically creates the **ix-apps** dataset for Docker storage for but separate datasets used for application data storage. <br><li>**Multiprotocol** - Select if configuring a multi-protocol or mixed-mode NFS and SMB sharing protocols. Allows clients to use either protocol to access the same data. Displays the **Create NFS Share** and **Create SMB Share** options pre-selected and the **SMB Name** field populated with the value entered in **Name**. See [Multiprotcol Shares]({{< relref "MixedModeShares.md" >}}) for more information. Sets the ACL to NFSv4.<br></li>Setting cannot be edited after saving the dataset. |
 {{< /truetable >}}
 {{< /expand >}}
 

content/TruenasApps/EnterpriseApps/_index.md

@@ -25,41 +25,7 @@ TrueNAS is certified with leading hypervisors and backup solutions to streamline
 TrueNAS Enterprise storage appliances deliver a wide range of features and scalability for virtualization and private cloud environments, with the ability to create off-site backups with scheduled sync and replication features.
 TrueNAS applications expand the capabilities of your system by adding third-party software but can add significant risk to system stability and security.
 
-Keep these general best practices in mind when using applications with TrueNAS:
-
-{{< expand "App Pool Selection" "v" >}}
-
-{{< include file="/static/includes/apps/AppsPoolOrDataset.md" >}}
-
-{{< /expand >}}
-
-{{< expand "App Dataset and File Sharing" "v" >}}
-
-{{< include file="/static/includes/apps/AppsFileSharing.md" >}}
-
-{{< /expand >}}
-
-{{< expand "Docker Compose Settings" "v" >}}
-
-{{< include file="/static/includes/apps/AppsDockerCompose.md" >}}
-
-{{< /expand >}}
-
-{{< expand "Custom Apps" "v" >}}
-
-{{< include file="/static/includes/apps/CustomAppIntro.md" >}}
-
-{{< include file="/static/includes/apps/AppsCustomApp.md" >}}
-
-{{< /expand >}}
-
-{{< expand "App Directory Services" "v" >}}
-
-{{< include file="/static/includes/apps/AppsDirectoryService.md" >}}
-
-iXsystems Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the [information customers provide]({{< relref "/SCALE/GettingStarted/Install/_index.md" >}}), but they do not configure customer Active Directory system settings.
-
-{{< /expand >}}
+{{< include file="/static/includes/apps/AppsBestPractices.md" >}}
 
 For more information on configuring general application functions and installation wizard screens, see [TrueNAS Apps]({{< relref "/content/TruenasApps/_index.md" >}}).
 

content/TruenasApps/_index.md

@@ -44,37 +44,7 @@ Make sure the application is required for your specific use requirements and doe
 
 You must choose a pool before you can install an application.
 
-{{< expand "App Pool Selection" "v" >}}
-
-{{< include file="/static/includes/apps/AppsPoolOrDataset.md" >}}
-
-{{< /expand >}}
-
-{{< expand "App Dataset and File Sharing" "v" >}}
-
-{{< include file="/static/includes/apps/AppsFileSharing.md" >}}
-
-{{< /expand >}}
-
-{{< expand "Apps General Settings" "v" >}}
-
-{{< include file="/static/includes/apps/AppsDockerCompose.md" >}}
-
-{{< /expand >}}
-
-{{< expand "Custom Apps" "v" >}}
-
-{{< include file="/static/includes/apps/CustomAppIntro.md" >}}
-
-{{< include file="/static/includes/apps/AppsCustomApp.md" >}}
-
-{{< /expand >}}
-
-{{< expand "App Directory Services" "v" >}}
-
-{{< include file="/static/includes/apps/AppsDirectoryService.md" >}}
-
-{{< /expand >}}
+{{< include file="/static/includes/apps/AppsBestPractices.md" >}}
 
 For more information on screens and screen functions, refer to the UI Reference article on [Apps Screens]({{< relref "SCALE/SCALEUIReference/Apps/_index.md" >}}).
 
@@ -88,7 +58,7 @@ You must set the pool before you can add any application.
 
 We recommend keeping the application use case in mind when choosing a pool.
 Select a pool with enough space for all the applications you intend to use.
-For stability, we also recommend using SSD storage for the applications pool.
+For stability, we recommend using SSD storage for the applications pool.
 
 Select the pool and click **Save**. If you close the dialog to set the pool later, click **Configuration > Choose Pool** to set the pool.
 

static/includes/CreateDatasetSCALE.md

@@ -14,7 +14,7 @@ Select the **Dataset Preset** option you want to use. Options are:
 
 If creating an SMB or multi-protocol (SMB and NFS) share the dataset name value auto-populates the share name field with the dataset name.
 
-If you plan to deploy container applications, the system automatically creates the **ix-applications** dataset, but this dataset is not used for application data storage.
+If you plan to deploy container applications, the system automatically creates the **ix-apps** dataset for Docker storage for but separate datasets used for application data storage.
 If you want to store data by application, create the dataset(s) first, then deploy your application.
 When creating a dataset for an application, select **Apps** as the **Dataset Preset**. This optimizes the dataset for use by an application.
 

static/includes/apps/AppsBestPractices.md

@@ -0,0 +1,37 @@
+

+
+Keep these general best practices in mind when using applications with TrueNAS:
+
+{{< expand "App Pool Selection" "v" >}}
+
+{{< include file="/static/includes/apps/AppsPoolOrDataset.md" >}}
+
+{{< /expand >}}
+
+{{< expand "App Dataset Types" "v" >}}
+
+{{< include file="/static/includes/apps/AppsDatasets.md" >}}
+
+{{< /expand >}}
+
+{{< expand "Apps General Settings" "v" >}}
+
+{{< include file="/static/includes/apps/AppsDockerCompose.md" >}}
+
+{{< /expand >}}
+
+{{< expand "Custom Apps" "v" >}}
+
+{{< include file="/static/includes/apps/CustomAppIntro.md" >}}
+
+{{< include file="/static/includes/apps/AppsCustomApp.md" >}}
+
+{{< /expand >}}
+
+{{< expand "App Directory Services" "v" >}}
+
+{{< include file="/static/includes/apps/AppsDirectoryService.md" >}}
+
+iXsystems Support can assist Enterprise customers with configuring directory service settings in TrueNAS with the [information customers provide]({{< relref "/SCALE/GettingStarted/Install/_index.md" >}}), but they do not configure customer Active Directory system settings.
+
+{{< /expand >}}

static/includes/apps/AppsDatasets.md

@@ -0,0 +1,63 @@
+

+
+**ix-apps Dataset**
+
+TrueNAS 24.10 and newer creates a hidden **ix-apps** dataset, mounted at <file>/mnt/.ix-apps</file>, to store Docker configuration, catalog data, and app metadata.
+The ix-apps dataset is internally managed by TrueNAS and hidden to prevent user misconfiguration.
+Any modification of it can result in instability and loss of app functionality.
+
+Do not include the ix-apps dataset inside of an SMB or NFS share.
+
+Back up and restore functionality as well as migration of the ix-apps dataset from one apps pool to another are not currently supported by the TrueNAS interface.
+Support for these features is planned for a future TrueNAS release version.
+
+{{< hint type="note" title="ix-Applications Dataset" >}}
+TrueNAS 24.04 and earlier versions stored applications data in an **ix-applications** dataset on the configured apps pool.
+Systems with applications deployed that upgrade from earlier releases to 24.10 retain the ix-applications dataset.
+During the migration process, 24.10 reads the stored Kubernetes app data in the ix-applications dataset, ports them to Docker, and saves them in the new ix-apps dataset.
+App storage ixVolumes present in ix-applications are cloned under the ix-apps dataset and promoted.
+
+The app data retained in ix-applications enables TrueNAS to revert to 24.04 with functional applications.
+TrueNAS 24.10 or newer does not use app data in the ix-applications dataset.
+It can be safely removed after fully migrating to 24.10, but apps will not function if reverted to 24.04 without the ix-applications dataset.
+{{< /hint >}}
+
+**ixVolume Datasets**
+
+**ixVolume** datasets allow TrueNAS to automatically create an app storage path inside the hidden ix-apps dataset.
+
+ixVolumes are typically created with appropriate permissions to deploy the application.
+If needed, use **Enable ACL** in **Storage Configuration** to configure ACL entries for an ixVolume.
+
+ixVolumes are not recommended for permanent storage volumes, they are intended for use as rapid storage for a test deployment of the container.
+Though they can simplify test deployment, ixVolumes complicate tasks like app data backup.
+We recommend manually adding datasets and configuring container storage volumes with the host path option.
+
+**Host Path Datasets**
+
+**Host Paths** allow users to mount existing TrueNAS datasets to paths within the app container.
+Create the TrueNAS dataset(s) before assigning them as host paths within the app installation screen.
+
+Mounting a host path does not automatically configure appropriate permissions to deploy the application.
+Use **Enable ACL** in **Storage Configuration** to configure ACL entries for each host path.
+
+{{< expand "Configuring Host Path ACL Entries" "v" >}}
+After entering the path inside the container in **Mount Path**, select **Enable ACL**.
+Browse to or enter the path to the dataset in **Host Path**.
+Click **Add** next to **ACL Entries** to display a set of ACE fields.
+Use **ID Type** to select whether the ACE is for a user or a group.
+Enter the UID or GID in **ID** and adjust the permissions level in **Access**.
+
+Refer to the app **Run As Context** on the app details screen for default ID requirements.
+A user or group ID does not need to exist locally on TrueNAS or match the name configured in the container to grant an ACE.
+Failing to configure host path ACLs prevents the app from deploying!
+
+Select **Force Flag** in **ACL Options**.
+This allows TrueNAS to write ACL entries to the storage volume if it has existing data in it.
+**Force Flag** is required to edit or update an existing application.
+{{< /expand >}}
+
+**SMB Share Volumes**
+
+Some app storage configurations include the **SMB/CIFS Share** option.
+Use this option to mount an existing SMB share using a Docker [volume](https://docs.docker.com/engine/storage/#volumes).

static/includes/apps/AppsInstallWizardSettings.md

@@ -31,40 +31,41 @@ All apps in the **stable** train, some **community** train apps, and all apps in
 * **Storage Configuration** shows options to configure storage for the application.
   Storage configuration can include the primary data mount volume, a configuration volume, postgres volumes, and an option to add additional storage volumes.
   The primary mount volumes have two options:
-* **ixVolume** that creates a storage volume inside the hidden **ix-apps** dataset. This is the default setting.
-* **Host Path** that allows you to select an existing dataset created for the application. Shows additional fields to select the path to the dataset and add the mount point.
+  * **ixVolume** creates a storage volume inside the hidden **ix-apps** dataset. This is the default setting.
+  * **Host Path** allows you to select an existing dataset created for the application. Shows additional fields to select the path to the dataset and add the mount point.
 
   ixVolumes are not recommended for permanent storage volumes, they are intended for use as rapid storage for a test deployment of the container.
   We recommend adding datasets and configuring the container storage volumes with the host path option.
 
-  Host path add existing dataset(s) as the storage volumes. You must configure the datasets before beginning the app installation using the wizard.
+  Host paths add existing dataset(s) as the storage volumes.
+  You must configure the datasets before beginning the app installation using the wizard.
 
-  {{< hint type="note" title="ix-apps Dataset" >}}
-  The **ix-apps** dataset is for internal use only.
-
-  TrueNAS systems with applications deployed that upgrade from earlier releases to 24.10 continue to see the **ix-Applications** dataset on the pool chosen for applications to use.
-  New installs or systems upgrading where applications are not deployed and a pool is not chosen for apps use the hidden **ix-apps** dataset.
-  Choosing the pool for apps to use, creates this dataset to store all container-related data.
-  To expose storage volumes found in the **ix-applications** dataset, take a recursive snapshot.
-  {{< /hint >}}
-
-  Some applications require specific storage volumes for configuration and other data. Apps with these requirements might indicate this in the wizard UI but refer to tutorials for specifics. 
-  After configuring required storage volumes you can add storage volumes.
+  Some applications require specific storage volumes for configuration and other data.
+  Apps with these requirements might indicate this in the wizard UI but refer to tutorials for specifics.
+  After configuring required storage volumes you can add additional storage volumes if needed.
   Click **Add** to select the type of storage and configure additional storage volumes for the application.
   The three storage options are:
   * **ixVolume**
   * **Host path**
-  * **SMB share** that allows you to create a storage volume used by an SMB share. 
+  * **SMB share** that allows you to mount an SMB share as a Docker storage volume.
 
-  An SMB share option allows you to configure a share for the application to use.
+  An SMB share option allows you to mount an SMB share as a Docker volume for the application to use.
   If the application requires specific datasets or you want to allow SMB share access, configure the dataset(s) and SMB share before using the installation wizard.
 
-  ixVolumes do not require setting up an ACL and ACE entry but host paths do.
-  After entering the dataset name as the mount point, select **Enable ACL** to browse to or enter the path to the dataset.
-  Enter the UID for either the default user assigned to the app or the UID for the TrueNAS user created to serve as the app administrator as the user in the ACE entry and set permissions to full control.
-  Failing to enable host path ACLs prevents the app from deploying!
+  ixVolumes do not require setting up an Access Control List (ACL) and Access Control Entry (ACE) in the app configuration settings, but host paths do.
+  After entering the path inside the container in **Mount Path**, select **Enable ACL**.
+  Browse to or enter the path to the dataset in **Host Path**.
+  Click **Add** next to **ACL Entries** to display a set of ACE fields.
+  Use **ID Type** to select whether the ACE is for a user or a group.
+  Enter the UID or GID in **ID** and adjust the permissions level in **Access**.
+
+  Refer to the app **Run As Context** on the app details screen for default ID requirements.
+  A user or group ID does not need to exist locally on TrueNAS or match the name configured in the container to grant an ACE.
+  Failing to configure host path ACLs prevents the app from deploying!
 
-  Select **Force** to allow TrueNAS to update the application to the next version. This allows updates and writing to the storage volume if it has data in it.
+  Select **Force Flag** in **ACL Options**.
+  This allows TrueNAS to write ACL entries to the storage volume if it has existing data in it.
+  **Force Flag** is required to edit or update an existing application.
 
 * **Resources Configuration** shows CPU and memory settings for the container pod.
    In most cases, you can accept the default settings, or you can change these settings to limit the system resources available to the application.

static/includes/apps/AppsPoolOrDataset.md

@@ -1,9 +1,6 @@
 

 
-We recommend users keep the container use case in mind when choosing a pool.
+We recommend users keep the container use case in mind when choosing an applications pool.
 Select a pool with enough space for all the application containers you intend to use.
 
-TrueNAS creates the **ix-apps** dataset on the chosen pool and uses it to store all container-related data. This is for internal use only.
-
-TrueNAS provides two default storage options, the default ixVolume or setting a host path to a preexisting dataset.
-If you intend to store your application data in a location separate from other storage on your system, create a new dataset before launching the app installation wizard.
+For stability, we recommend using SSD storage for the apps pool.