Remove old 7.x permissions in an 8.0.x update hook

Problem/Motivation

The 8.x-7.x version of the module defines some permissions which are not defined in the 8.0.x version:

1. administer elasticsearch connector
2. administer elasticsearch cluster
3. administer elasticsearch index

After upgrading the module's code (i.e.: with composer), and running database updates (i.e.: to migrate the configuration to Search Api Servers and Indexes), trying to modify a role that used to have those permissions would result in errors like...

RuntimeException: Adding non-existent permissions to a role is not allowed. The incorrect permissions are "administer elasticsearch cluster", "administer elasticsearch connector", "administer elasticsearch index". in Drupal\user\Entity\Role->calculateDependencies() (line 210 of core/modules/user/src/Entity/Role.php).

... or in some cases, just exporting configuration would result in errors like...

In Role.php line 207:

Adding non-existent permissions to a role is not allowed. The incorrect permissions are "administer elasticsearch cluster", "administer elasticsearch connector", "administer elasticsearch index".

Steps to reproduce

1. Download and install Drupal 10 core (D10 for compatibility with elasticsearch_connector-8.x-7.x — I got 10.3.6)
   

   mkdir issue3479941 && cd issue3479941
   ddev config --project-type=drupal --php-version=8.3 --docroot=web
   ddev start
   ddev composer create drupal/recommended-project:^10
   ddev config --update
   ddev composer require drush/drush
   ddev drush -y site:install minimal
   

2. Download and install Search API 1 (I got 1.35.0)
   

   ddev composer require 'drupal/search_api:^1'
   ddev drush -y pm:install search_api
   

3. Download and install Elasticsearch Connector 7 (I got 8.x-7.0-alpha5)
   

   ddev get ddev/ddev-elasticsearch && ddev restart
   ddev composer config minimum-stability dev
   ddev composer require 'drupal/elasticsearch_connector:^7'
   ddev drush -y pm:install elasticsearch_connector
   

4. Create a new role (I gave mine the machine name elastic_admin) and grant the administer elasticsearch connector, administer elasticsearch cluster and administer elasticsearch index permissions
   

   ddev drush -y role:create elastic_admin 'ElasticSearch administrator'
   ddev drush -y role:perm:add elastic_admin 'administer elasticsearch connector'
   ddev drush -y role:perm:add elastic_admin 'administer elasticsearch cluster'
   ddev drush -y role:perm:add elastic_admin 'administer elasticsearch index'
   

5. Log in to the web UI
   ddev drush -y uli
6. Add an ElasticSearch Cluster from /admin/config/search/elasticsearch-connector/cluster/add (I gave mine the machine name es_cluster_test and I could use ddev's Server URL http://elasticsearch:9200
7. Add an ElasticSearch Index from /admin/config/search/elasticsearch-connector/index/add (I gave mine the machine name es_index_test)
8. Add a Search API Server from /admin/config/search/search-api/add-server (I gave mine the machine name sapi_test)
9. Export configuration
   ddev drush -y config:export
10. Upgrade Elasticsearch Connector to version 8 (I had to composer-remove elasticsearch_connector 7 and composer-require elasticsearch_connector 8) and run database updates
    

    ddev composer remove 'drupal/elasticsearch_connector' && ddev composer require 'drupal/elasticsearch_connector:^8'
    ddev drush -y updatedb
    

11. Go to /admin/people/permissions/elastic_admin, change a permission (I granted 'Administer blocks'), and click "Save permissions"
    • Expected behavior: Permissions are saved
    • Actual behavior: You get a RuntimeException: Adding non-existent permissions to a role is not allowed. The incorrect permissions are "administer elasticsearch cluster", "administer elasticsearch connector", "administer elasticsearch index". in Drupal\user\Entity\Role->calculateDependencies() (line 210 of core/modules/user/src/Entity/Role.php).
12. Note on my production site, I could reproduce a similar error by exporting configuration, but it didn't happen in my test environment when I was writing these steps:
    ddev drush -y config:export
    • Expected behavior: Permissions exported successfully
    • Actual behavior: You get a
      

      In Role.php line 207:
      
      Adding non-existent permissions to a role is not allowed. The incorrect permissions are "administer elasticsearch cluster", "administer elasticsearch connector", "administer elasticsearch index".
            

Proposed resolution

There are similar permissions in search_api, but they grant wider access to add servers/indexes of any type. Instead of replacing the old elasticsearch_connector-7 permissions with the similar-but-broader-scope Search API permissions, a safer solution would be to remove the old elasticsearch_connector-7 permissions during the database update.

Note also that elasticsearch_connector-7 has no usable UI without Search API, so it seems pretty likely to me that users with the old elasticsearch_connector-7 permissions likely also have the equivalent Search API permissions.

We should probably also write a change record for this.

Remaining tasks

1. Write a patch
2. Write change records
3. Review and feedback
4. RTBC and feedback
5. Commit
6. Publish change records
7. Release - released in 8.0.0-alpha3

User interface changes

None.

API changes

None.

Data model changes

None.