Bug 1267439 - [DOCS] [Use Case] Document the Upgrade Process from 3.0.x to 3.1
[DOCS] [Use Case] Document the Upgrade Process from 3.0.x to 3.1
Status: CLOSED CURRENTRELEASE
Product: OpenShift Container Platform
Classification: Red Hat
Component: Documentation (Show other bugs)
3.0.0
Unspecified Unspecified
high Severity high
: ---
: ---
Assigned To: Alex Dellapenta
Anping Li
Vikram Goyal
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2015-09-29 23:41 EDT by Vikram Goyal
Modified: 2017-12-30 19:31 EST (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2017-12-30 19:31:04 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Vikram Goyal 2015-09-29 23:41:49 EDT
As a customer, I want to know:

* How do I upgrade from 3.0.x branch to 3.1.
* 

Suggested topics:

1.1 Before you begin
1.1.1 System requirements
1.1.2 Subscription management

1.2 Detailed upgrade process

This should go in:

* Install and Config Guide.
* (Possibly in the What's New Guide?)
Comment 2 Alex Dellapenta 2015-11-05 23:16:48 EST
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).
Comment 3 Alex Dellapenta 2015-11-16 17:14:01 EST
PR submitted, seeking initial tech review:

https://github.com/openshift/openshift-docs/pull/1199
Comment 5 Anping Li 2015-11-16 22:28:24 EST
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
Comment 6 Alex Dellapenta 2015-11-16 22:33:33 EST
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
Comment 7 Alex Dellapenta 2015-11-16 22:34:29 EST
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.
Comment 8 Alex Dellapenta 2015-11-16 22:57:31 EST
(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
Comment 9 Anping Li 2015-11-17 00:10:11 EST
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.
Comment 10 Alex Dellapenta 2015-11-17 00:19:05 EST
(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?
Comment 11 Anping Li 2015-11-17 00:29:27 EST
Yes, it should be run.  only the file path need to be adjust.
Comment 12 Alex Dellapenta 2015-11-17 00:31:12 EST
(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?
Comment 13 Anping Li 2015-11-17 00:36:07 EST
The step will be automate run by playbook?   it only need to be run if we upgrade manually.
Comment 14 Anping Li 2015-11-17 00:39:04 EST
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
Comment 15 Alex Dellapenta 2015-11-17 00:43:26 EST
(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.
Comment 16 Alex Dellapenta 2015-11-17 01:06:42 EST
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
Comment 17 Anping Li 2015-11-17 01:16:35 EST
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.
Comment 18 Anping Li 2015-11-17 02:20:39 EST
(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'
Comment 19 Anping Li 2015-11-17 02:41:47 EST
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'
Comment 20 Anping Li 2015-11-17 03:29:22 EST
The atomic-openshift service should be enabled after upgrade.
systemctl enable atomic-openshift-node
systemctl enable atomic-openshift-master
Comment 21 Alex Dellapenta 2015-11-17 15:34:13 EST
(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
Comment 22 Anping Li 2015-11-17 21:15:39 EST
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.
Comment 23 Alex Dellapenta 2015-11-18 12:36:04 EST
(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
Comment 24 Anping Li 2015-11-18 21:21:52 EST
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'.
Comment 27 Alex Dellapenta 2015-11-23 16:59:48 EST
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?
Comment 29 Anping Li 2015-11-24 02:32:54 EST
(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.
Comment 34 Alex Dellapenta 2015-11-24 10:08:08 EST
(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
Comment 35 Alex Dellapenta 2015-11-24 10:59:34 EST
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
Comment 36 Anping Li 2015-11-25 03:34:28 EST
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
Comment 38 Vikram Goyal 2017-12-30 19:31:04 EST
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.

Note You need to log in before you can comment on or make changes to this bug.