Bug 1267439

Info on using the automated upgrade playbook has been added here:

https://docs.openshift.com/enterprise/3.1/install_config/upgrades.html

Specific steps for alternatively doing a manual update for 3.1 still incoming (and will be removing the 3.0.z-related info for the enterprise-3.1 version of this topic).

PR submitted, seeking initial tech review:

https://github.com/openshift/openshift-docs/pull/1199

1. Part : Using the Automated Upgrade Playbook
The upgrade playbook  is integrated in  atomic-openshift-utils-3.0.12.  So there are two way to get the playbook. it is better to use method a
  a. yum install atomic-openshift-utils-3.0.12
  b. git pull https://github.com/openshift/openshift-ansible master
2. There are two way for Automated Upgrade. The first one: atomic-openshift-installe. the second one: ansible-playbook
   If you installed using oo-install and your oo-install configuration file was kept. you should use the commond "atomic-openshift-installer upgrade".
   If you installed using oo-install, but your oo-install configure file wasn't kept. we need provide a template.
   if you installed by advance installation. the upgrade command is 'ansible-playbook [-i /path/to/hosts/file] /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-cluster/upgrades/v3_0_to_v3_1/upgrade.yml

Were you reviewing the build here? http://file.rdu.redhat.com/~adellape/111615/31_upgrade/install_config/upgrades.html

The one part I know I definitely need to fix is the filename of the playbook to use in http://file.rdu.redhat.com/~adellape/111615/31_upgrade/install_config/upgrades.html#upgrading-using-ansible-directly

Also, for OSE, we're not going to show the "clone the openshift-ansible repo" method, since it's packaged with atomicopenshift-utils, as you mention.

(In reply to Anping Li from comment #5)

>    if you installed by advance installation. the upgrade command is
> 'ansible-playbook [-i /path/to/hosts/file]
> /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-cluster/
> upgrades/v3_0_to_v3_1/upgrade.yml

^ Fixed in https://github.com/openshift/openshift-docs/pull/1203

Please review build at http://file.rdu.redhat.com/~adellape/111615/31_upgrade/install_config/upgrades.html

http://file.rdu.redhat.com/~adellape/111615/31_upgrade/install_config/upgrades.html#additional-instructions-per-release

At part: Removing Support for the v1beta3 API
The default directory should be /etc/openshift/master/master-config.yml.

(In reply to Anping Li from comment #9)
> http://file.rdu.redhat.com/~adellape/111615/31_upgrade/install_config/
> upgrades.html#additional-instructions-per-release
> 
> At part: Removing Support for the v1beta3 API
> The default directory should be /etc/openshift/master/master-config.yml.

Does this mean it should this step be performed before running the upgrade?

Yes, it should be run.  only the file path need to be adjust.

(In reply to Anping Li from comment #11)
> Yes, it should be run.  only the file path need to be adjust.

Before or after running the playbook?

The step will be automate run by playbook?   it only need to be run if we upgrade manually.

At Part:
Add the master proxy client certificates to the /etc/origin/master/master-config.yml file on each master:

  - kubernetesMasterConfig.proxyClientInfo.certFile: master.proxy-client.crt
  - kubernetesMasterConfig.proxyClientInfo.keyFile: master.proxy-client.key


It is better to use same format with master-config.yml. For example:

kubernetesMasterConfig:
  proxyClientInfo:
    certFile: master.proxy-client.crt
    keyFile: master.proxy-client.key

(In reply to Anping Li from comment #13)
> The step will be automate run by playbook?   it only need to be run if we
> upgrade manually.

Sorry for the confusion, got things mixed up for a minute. Thanks.

Feedback addressed in https://github.com/openshift/openshift-docs/pull/1207

New preview build to reflect the changes:

http://file.rdu.redhat.com/~adellape/111615/fix_addtl_upgrade/install_config/upgrades.html

The part "Create and Add Master Proxy Client Certificates" should be a post steps (after installed atomic-openshift-master 3.1 ).  The oadm before v3.1 couldn't create proxyClientInfo proxy.

(In reply to Anping Li from comment #17)
> The part "Create and Add Master Proxy Client Certificates" should be a post
> steps (after installed atomic-openshift-master 3.1 ).  The oadm before v3.1
> couldn't create proxyClientInfo proxy.

I suggest to move 'Create and Add Master Proxy Client Certificates" behind '
yum upgrade atomic-openshift-master'

In Upgrading Nodes:
It is better to add SchedulingDisabled tag before upgrade. and turn on after upgrade.
The command is 'oadm manage-node bide1.example.com --schedulable=false/true'

The atomic-openshift service should be enabled after upgrade.
systemctl enable atomic-openshift-node
systemctl enable atomic-openshift-master

(In reply to Anping Li from comment #18)
> (In reply to Anping Li from comment #17)
> > The part "Create and Add Master Proxy Client Certificates" should be a post
> > steps (after installed atomic-openshift-master 3.1 ).  The oadm before v3.1
> > couldn't create proxyClientInfo proxy.
> 
> I suggest to move 'Create and Add Master Proxy Client Certificates" behind '
> yum upgrade atomic-openshift-master'

^ "Create and Add Master Proxy Client Certificates" is already a post-upgrade step, as the beginning of the OSE 3.1.0 section in "Additional Manual Steps Per Release" section starts off saying "After finishing the standard manual upgrade steps..."

For the other two issues (disabling/enabling scheduling and enabling the new services), those have been addressed in https://github.com/openshift/openshift-docs/pull/1209

Preview build (internal):

http://file.rdu.redhat.com/~adellape/111715/upgrade_qe_edits/install_config/upgrades.html

Without the step 'Create and Add Master Proxy Client Certificates', atomic-openshift-master can't be started. so it must be behind 'yum install atomic-openshift-master' and be prior 'systemctl start atomic-openshift-master' 

And it is better to place 'systemctl enable atomic-openshift-master/node' before start them.

(In reply to Anping Li from comment #22)
> Without the step 'Create and Add Master Proxy Client Certificates',
> atomic-openshift-master can't be started. so it must be behind 'yum install
> atomic-openshift-master' and be prior 'systemctl start
> atomic-openshift-master' 
> 
> And it is better to place 'systemctl enable atomic-openshift-master/node'
> before start them.

Thanks for the clarification. Feedback addressed in https://github.com/openshift/openshift-docs/pull/1218

Preview build (internal) here:

http://file.rdu.redhat.com/~adellape/111815/proxyclientcerts_upgrade/install_config/upgrades.html

The part: 'Updating the Default Image Streams and Templates'. 
In this part, the description will make customer confuse. it is better to  tell customer directly how to to fetch these example files. 
one suggestion is " Install atomic-openshift-unitily at the beginning for Upgrading Manually"
another suggestions is tell customer to install atomic-openshift-unitily or fetch files from githup at this part.


For part: Additional Manual Steps Per Release
You need change 'After finishing the standard manual upgrade steps' to something like 'before start manual upgrade steps'.

Feedback addressed in https://github.com/openshift/openshift-docs/pull/1251. See PR description for links / more comments. 

Also, this comment above:

> For part: Additional Manual Steps Per Release
You need change 'After finishing the standard manual upgrade steps' to something like 'before start manual upgrade steps'.

^ Is there a specific reason those two steps ("Removing Support for the v1beta3 API" and "Creating Symlinks for New Directories") should happen before the manual upgrade steps?

(In reply to Alex Dellapenta from comment #27)
> Feedback addressed in https://github.com/openshift/openshift-docs/pull/1251.
> See PR description for links / more comments. 
> 
> Also, this comment above:
> 
> > For part: Additional Manual Steps Per Release
> You need change 'After finishing the standard manual upgrade steps' to
> something like 'before start manual upgrade steps'.
> 
> ^ Is there a specific reason those two steps ("Removing Support for the
> v1beta3 API" and "Creating Symlinks for New Directories") should happen
> before the manual upgrade steps?

Without "Creating Symlinks for New Directories", the new atomic-openshift-master/node service can't be started.

(In reply to Alex Dellapenta from comment #27)
> Feedback addressed in https://github.com/openshift/openshift-docs/pull/1251.
> See PR description for links / more comments. 

^ I mentioned here they were in the PR. I'll copy/paste the preview links:

http://file.rdu.redhat.com/~adellape/112315/upgrade_edit3/install_config/upgrades.html#updating-policy-definitions

http://file.rdu.redhat.com/~adellape/112315/upgrade_edit3/install_config/upgrades.html#updating-the-default-image-streams-and-templates

Also I've now moved the "removing v1beta3 API" and "creating symlink" steps up inline to the "Preparing for a Manual Upgrade" section:

http://file.rdu.redhat.com/~adellape/112315/upgrade_edit3/install_config/upgrades.html#preparing-for-a-manual-upgrade

This part: 2. Create an etcd backup on each master

The description about etcd backup isn't accurate。
Although Etcd had been integrated with master, Openshift allow access external etcd database.

If we use internal etcd,  for v3.0, the etcd datafile are stored in /var/lib/openshift/openshift.local.etcd. for v3.1, it is in /var/lib/origin/openshift/openshift.local.etcd.

If we use external etcd. it maybe installed outside of master. by default the datafile are stored under /var/lib/etcd

I am going to close this bug as this is quite old now and we have moved on from 3.0 to 3.1 upgrade.

If there are still issues with this upgrade, please open a new one.