ARTIFACTORY: Resolving Property Key Issues in Archive Operation

Introduction 

This article addresses the issue of property keys containing slashes (/) in Artifactory, which are causing operation failures.
The reason you are seeing this issue now is that older versions of Artifactory permissively allowed slashes (/) in property keys. However, newer versions enforce a stricter validation rule to maintain data integrity and consistency with JFrog REST API standards.
This new, stricter validation prevents the use of certain special characters (like /) in property keys, which can lead to failures during operations such as artifact deployment, promotion, or archiving.
The steps outlined in this guide will help you identify these legacy property keys and update them for seamless operation under the current validation rules.


Docker Repository Context

For Docker repositories, properties are typically stored directly on the manifest.json file. Therefore, the database queries below specifically target nodes with node_name=′manifest.json′, which is crucial for precisely identifying the offending properties on Docker images without affecting other file types.


Problem

Archive operations fail because property keys containing slashes (/)—which appear as the URL-encoded character %2F in the logs—violate Artifactory's character restrictions for property names.

xxxxxx [jfrt ] [ERROR] [xxxxxxxxxxx] [.c.t.ArchiveDeployRunnable:155] [7|pool-6334-thread-1] - Deploy request https://xxxxxx/artifactory/xjaksicksj_docker-prereleases-local/xxxxxx/latest/manifest.json; 
failed because of unexpected status code 400. Error message: {
  "errors" : [ {
    "status" : 400,
    "message" : "Property key: docker.label.docker.test%2Fbinds is invalid due to Name must begin with a letter, cannot contain a whitespace, and cannot contain the following special characters: )(}{][-*+^$\\/~`!@#%&<>;=,±§."
  } ]
}

The key problem is the property docker.label.docker.test%2Fbinds which decodes to docker.label.docker.test/binds.


Resolution

The resolution involves querying the database to find the illegal property keys, replacing the slash character (/), and retesting the operation.

Step 1: Identify Property Keys with Slashes

To determine how many property keys contain a slash (/), run the following SQL query:

SELECT prop_id, node_id, prop_key
FROM node_props
WHERE node_id IN (
    SELECT node_id
    FROM nodes
    WHERE repo = 'docker-prereleases-local' 
    AND node_type = 1 
    AND node_name = 'manifest.json' -- Crucial for Docker image properties
)
AND prop_key LIKE '%/%';

This query retrieves all entries from the node_props table where prop_key contains a slash, for the specified repository and node type.

Step 2: Create Backup for Rollback

Before running the update command, create a temporary table to back up the original prop_key values for all records that will be modified.

CREATE TEMPORARY TABLE backup_node_props AS 
SELECT prop_id, node_id, prop_key
FROM node_props
WHERE node_id IN (
    SELECT node_id
    FROM nodes
    WHERE repo = 'docker-prereleases-local' 
    AND node_type = 1 
    AND node_name = 'manifest.json' 
)
AND prop_key LIKE '%/%';
-- Verification (Optional): Check the contents of the backup table
SELECT * FROM backup_node_props;

This temporary table will exist for the duration of your current database session and can be used to revert the changes if necessary.

Step 3: Update Property Keys

After identifying the affected property keys, you can update them by replacing the slashes (/) with dots (.). Use the following SQL statement for the update:
 
Performance Warning for Large Installations
ATTENTION: The node_props table can be extremely large in big Artifactory installations. Executing a massive UPDATE operation, especially one that uses nested SELECT statements (IN), can cause significant database load, transaction log saturation, and potentially database lock contention leading to temporary performance degradation across the entire JFrog Platform.

Pre-Execution Measurement
Before running the update, you must measure the anticipated execution time to assess the impact:

Run an Execution Plan: Use your database's tools (EXPLAIN in PostgreSQL/MySQL, SET AUTOTRACE in Oracle, or SSMS tools in MSSQL) to generate the execution plan for the UPDATE query.
Estimate Impact: If the estimated execution time is long (e.g., more than a few minutes), consider running the update during a scheduled maintenance window or breaking the update into smaller, manageable batches.


Update Statement
Use the following SQL statement to replace all occurrences of '/' with '.' in the identified property keys:

UPDATE node_props
SET prop_key = REPLACE(prop_key, '/', '.')
WHERE node_id IN (
    SELECT node_id
    FROM nodes
    WHERE repo = 'docker-prereleases-local' AND node_type = 1 AND node_name = 'manifest.json'
)
AND prop_key LIKE '%/%';

This command efficiently replaces all occurrences of '/' with '.' in the identified property keys.


Rollback Procedure (If Necessary)
If the update causes unexpected issues, you can roll back the changes using the temporary table created in Step 2:

UPDATE node_props np
SET prop_key = bnp.prop_key
FROM backup_node_props bnp
WHERE np.prop_id = bnp.prop_id;


Step 4: Test Archive Operation

Once you have updated the property keys, perform the archive operation again to confirm that the problem has been resolved.

Step 5: Troubleshooting

If you encounter any issues during the archive operation, please gather the new log files and check for any error messages. 
Additional Information
AQL Query for Property Keys

For more context on how to search for property keys in Artifactory using the AQL (Artifactory Query Language), you can use the following curl command:

curl -u admin:Password 'http://localhost:8081/artifactory/api/search/aql' -H 'content-type: text/plain' -d 'items.find(
{"repo":"docker-prereleases-local"},
{"name":"manifest.json"},
{"property.key": {"$match":"*/*"}}
).include("repo","path","name","property.key","property.value")'

This AQL query finds all manifest.json files in the specified repository that have property keys containing a slash (/).

Reference Documentation: JFrog REST APIs - Set Item Properties
The JFrog documentation details that such characters are not allowed in property keys.


Conclusion

By following these steps, you successfully identify and resolve property keys containing disallowed characters in Artifactory, particularly those associated with Docker image manifests, allowing archive operations to complete successfully.